Process PhysX Collider Assets

Open 3D Engine (O3DE) has a robust set of options for generating PhysX collider assets. In Scene Settings, you can customize PhysX collider asset generation. The generated PhysX colliders are stored in .pxmesh product assets. You can add the PhysX collider assets to a PhysX Mesh Collider component.

The generated PhysX colliders are stored in .pxmesh product assets. You can add the PhysX collider assets to a PhysX Mesh Collider component.

Note:

Understanding the best practices for creating PhysX collider source assets can mitigate issues you might encounter when processing colliders for O3DE. For technical details about the data supported by colliders, refer to the supported 3D scene data table.

Entity behavior

Before you learn about collider types, you should understand the three types of entity behavior that influence the collider asset type you might choose in a given scenario:

• Static – Static entities have a PhysX Static Rigid Body and can be collided with, but they don’t move, and PhysX collisions and forces don’t affect them. Static entities can use any collider type.
• Kinematic – Kinematic entities have a PhysX Dynamic Rigid Body component and movement that is driven by code or script. Kinematic entities can be collided with, but PhysX collisions and forces don’t affect them. Kinematic entities can use any collider type.
• Simulated – Simulated entities have a PhysX Dynamic Rigid Body component and simulated movement that results from PhysX collisions and forces. Simulated entities can use only primitive and convex colliders.

PhysX collider assets

Collider assets are based on input meshes that you specify in Scene Settings. You can use a single input mesh, use multiple input meshes, or even specify that multiple input meshes should be merged and welded into a single mesh before the collider asset is generated. The source asset is not altered when the collider asset is generated.

Because physics simulation can be computationally expensive, it’s important to understand the various collider types, their limitations, and the scenarios in which you can use them.

Triangle Mesh

As the name implies, triangle mesh colliders are composed of triangle meshes. You can create a simplified mesh in a digital content creation (DCC) application specifically for the collider, or generate a triangle mesh collider based on the render mesh of the asset. Triangle mesh colliders can closely approximate a complex render mesh, but you can use them only with static and kinematic entities. Because triangle mesh colliders can contain many vertices, and the collider asset is not required to be convex, these colliders generally incur a higher performance cost than primitive colliders.

Triangle mesh colliders can have multiple physics material assignments. Because the collider is derived from the input mesh, you can apply a physics material to the collider for each material assignment. This is particularly useful for ground and floor colliders that transition between materials such as concrete and dirt, or wood planks and carpet.

Colliders occupy the same physical space as the input mesh. In the following image, a triangle mesh collider asset is offset to the right of the input mesh asset that generated the collider so that you can clearly view the collider. Note that the collider asset (right) accurately represents the render mesh (left), and that the collider supports separate physics materials for the front and back faces (magenta wireframe) and side faces (teal wireframe) of the mesh.

Triangle mesh colliders are commonly used for immobile environment objects that have complex shapes, such as tree trunks, floors, large stone and architectural features, and statues.

Primitive

Primitive colliders are composed of sphere, box, or capsule primitive shapes. Because simple properties such as Radius, Height, and Width define the primitive shapes, primitive colliders generally offer the best simulation performance. Primitive colliders are automatically fitted to the input mesh. However, depending on the complexity of the input mesh, areas of the collider might fall within or far outside of the input mesh surface. This can result in collisions that aren’t visually accurate. The Decompose Meshes property decomposes complex input meshes into smaller parts, and fits primitive colliders to each part. You can use primitive colliders with static, kinematic, and simulated entities. These colliders can have only one physics material assignment.

Colliders occupy the same physical space as the input mesh. In the following image, a primitive collider asset is offset to the right of the input mesh asset that generated the collider so that you can clearly view the collider. The collider asset (right) is a simple box that has been automatically oriented and scaled to encompass the render mesh (left). Note that one corner of the primitive collider extends far from the input mesh and penetrates the ground plane. This demonstrates one of the drawbacks of using a primitive collider on a complex input mesh. In a scenario where this is a simulated entity, the ground plane collision would push the asset upward, and the asset would not come to rest standing upright because of the sharp corner at the bottom of the primitive collider.

Primitive colliders are commonly used when the input mesh closely resembles one of the simple primitive shapes, and in scenarios where fast dynamic collision resolution is more important than visual accuracy.

Convex

Convex colliders are automatically generated convex hulls. A convex hull has no concave or hollow surface areas. For PhysX, the convex hull is constructed within a limited number of vertices and is fitted to the input mesh. Convex colliders can better approximate a complex input mesh than primitive colliders, but convex colliders incur a greater performance cost. To a lesser extent than primitive colliders, convex colliders might also have areas where the collider surface falls inside or outside of the input mesh, which can result in collisions that aren’t visually accurate. The Decompose Meshes property decomposes complex input meshes into smaller parts, and fits convex colliders to each part. You can use convex colliders with static, kinematic, or simulated entities. These colliders can have only one physics material assignment.

Colliders occupy the same physical space as the input mesh. In the following image, a convex collider asset is offset to the right of the input mesh asset that generated the collider so that you can clearly view the collider. Note that the collider asset (right) has been automatically generated to encompass and roughly approximate the silhouette shape of the render mesh (left). However, the convex collider does not include details such as the hole in the middle of the input mesh.

Convex colliders are commonly used on entities with complex render meshes that must be dynamically simulated, such as interactive props, and on entities that must be decomposed into smaller parts to provide collisions with a higher level of visual accuracy.

Summary

The following table summarizes the most import information about the available collider types:

Generate PhysX collider assets

You can generate PhysX collider assets from any source asset that contains at least one mesh. You can customize the settings for PhysX collider generation in Scene Settings, in the PhysX tab. If you are unfamiliar with Scene Settings, refer to the mesh processing tutorial and check the Scene Settings PhysX tab topic for in-depth information on the options for generating PhysX collider assets.

You can follow this tutorial using any source asset that contains at least one mesh.

1. In O3DE Editor, in Asset Browser, locate your source asset. If you don’t have an asset of your own, in the search field at the top of Asset Browser, you can type fbx and use one of the provided .fbx files, such as sphere.fbx.

   

   If your asset has already been processed, you might see a preview image of the asset and a list of product assets below the .fbx source asset.

2. To open Scene Settings, right-click the .fbx source asset, and then choose Edit settings… from the context menu.

   

3. The Scene Settings window presents different tabs depending on the contents of the source asset file. Select the PhysX tab. If the tab is empty, to create a PhysX mesh group, choose Add another physxmesh.

   

   In this image, there is a single PhysX mesh group. Each PhysX mesh group produces a .pxmesh product asset. You can create additional PhysX mesh groups for a source asset by choosing Add another physxmesh.

   The Name PhysX Mesh property contains the name of the source asset. The .pxmesh product asset of this PhysX mesh group uses this string for its name.

4. To select which meshes to include in the PhysX mesh group, next to the Select meshes property, choose the file select button. Meshes in the list are denoted by a purple mesh icon, as in the following image. You can select more than one mesh here if multiple meshes are available in the asset. If you select more than one mesh, you might additionally enable the Merge Meshes and Weld Vertices properties to ensure that the input mesh is optimized.

   

   Note:

   To automatically assign meshes in the source asset to a PhysX mesh group, add the suffix _phys to the mesh node name in your DCC application. Any meshes that have _phys postfixed to their node name in the source asset are excluded from the default render mesh group and are automatically added to a single PhysX mesh group in Scene Settings.

5. Customize the PhysX mesh collider type by setting the Export As property to Convex so that you can create any type of entity (static, kinematic, or simulated).

   The customizations that you make in Scene Settings are stored in a sidecar file with a .assetinfo extension. When Asset Processor detects a .assetinfo file, it uses the settings in the file to process the related source asset. This sidecar file is treated as a source dependency for the asset. This means that if the .assetinfo file changes, the source asset is reprocessed, even if the source asset has not changed.

6. At the bottom right of Scene Settings, choose Update. This creates or updates the .assetinfo sidecar file and triggers Asset Processor to reprocess the asset.

7. Drag the .azmodel product asset from Asset Browser into the viewport.

   
   
   

   When you drag the asset into the viewport, O3DE automatically creates an entity with a Mesh component that references the mesh product asset. If the source asset contains materials that have been processed, the materials are automatically applied to the mesh. Note that in Asset Browser, the .pxmesh product asset has been generated and appears beneath the source asset.

8. Add a PhysX Mesh Collider component to the entity. With the entity selected in the viewport, in Entity Inspector, choose Add Component, and then select PhysX Mesh Collider from the component list. The component automatically detects the .pxmesh asset and assigns it to the PhysX Mesh property.

9. Depending on the type of entity that you want, do one of the following:

   • For a static entity, , add a PhysX Static Rigid Body component. With the entity selected in the viewport, in Entity Inspector, choose Add Component, and then select PhysX Static Rigid Body from the component list. To optimize your current static entity, in the Transform component, enable the Static property. This property ensures the best runtime performance for a static entity.

   • For a simulated entity, add a PhysX Dynamic Rigid Body component. With the entity selected in the viewport, in Entity Inspector, choose Add Component, and then select PhysX Dynamic Rigid Body from the component list. If you choose the simulation button now, the entity drops with gravity.

   • For a kinematic entity, add a PhysX Dynamic Rigid Body component, like you would for a simulated entity. Then, in the PhysX Dynamic Rigid Body component, select Kinematic in the property Type.

   Caution:

   For a kinematic or simulated entity, in the Transform component, make sure that the Static property is not enabled.

Decompose input meshes

Assets that are composed of multiple meshes, or assets that have complex meshes, might require similarly complex PhysX collider assets. This is particularly true for kinematic entities and for simulated entities, which can’t use triangle mesh colliders. In these scenarios, you can decompose the input mesh into convex parts. You can automatically generate primitive colliders or convex colliders, fit them to each part, and process them as collider .pxmesh product assets.

Mesh decomposition is part of the process of generating and fitting collider assets, and it doesn’t alter the input mesh. You can use mesh decomposition only with primitive or convex colliders.

Note:

In O3DE, mesh decomposition uses the V-HACD library. For more information, including example images demonstrating decomposition of complex meshes, refer to the V-HACD library on GitHub.

To use mesh decomposition, do the following:

1. In Scene Settings, under PhysX Mesh group, for Export As, choose either Primitive or Convex.
2. Enable Decompose Meshes.

Enabling Decompose Meshes reveals many options that you can use to fine-tune mesh decomposition. For guidance on mesh decomposition options, refer to the Decompose meshes section of the Scene Settings PhysX Tab topic.

Primitive decomposition

When you enable Decompose meshes for primitive colliders, the input mesh is decomposed into convex parts. The best fitting primitive shapes are automatically selected and transformed to encompass each part and the primitives are processed as a collider .pxmesh product asset. In the following image, the input mesh (left) is decomposed into four parts, and a primitive collider is automatically fitted to each part (right). The parts are fitted with box primitive colliders.

Convex decomposition

When you enable Decompose meshes for convex colliders, the input mesh is decomposed into convex parts. A convex hull is generated for each part and the convex hulls are processed as a collider .pxmesh product asset. In the following image, the input mesh (left) is decomposed in to four parts and convex hulls are generated for each part (right). The convex colliders provide a fairly accurate representation of the render mesh which may be sufficient in many scenarios.

In general, collider assets generated with decomposed meshes provide a more accurate representation of the render mesh than a single primitive or convex collider can. For example, notice that in both of the preceding results, the collider surface doesn’t block the hole in the middle of the logo, unlike in the first example image of the convex collider asset type.