User Guide (Version 1.17)

Exporting a PxMesh for PhysX Mesh Shape

To use the PhysX Mesh Shape component, you need a .pxmesh file to define the entity's collision geometry. You create this file from an FBX file with at least one mesh. Lumberyard's PhysX system can export a mesh as a triangular mesh or a convex mesh. The default is set to triangular mesh, which you can use only on static objects. The following procedure shows you how to export your mesh with various settings.

To export a .pxmesh file

  1. On your file system, locate the FBX file with the mesh that you want to export. Artists typically create these FBX files with DCC tools.

                        FBX file on the operating system
  2. Place the FBX file into your project's asset directory. For example, lumberyard_version\dev\StarterGame\Objects. If Lumberyard Editor is not open, launch it.

    Lumberyard's Asset Processor automatically detects and process the new FBX file.

  3. In the Asset Browser, navigate to the FBX file. Right-click and choose Edit Settings to open the FBX Settings window.

                        Right-click the FBX file and choose Edit Settings
  4. To configure PhysX mesh export parameters:

    1. Select the PhysX tab (1).

    2. If this .pxmesh file is for a dynamic object, you must select Export Mesh As Convex (2). If the file is for a static object, selecting this parameter is optional.

      When enabled, this parameter exports the mesh as a convex mesh. Otherwise, the mesh is exported as a triangular mesh.

    3. In the Select meshes box (3), at least one mesh must be selected. If no meshes are selected, click Select meshes (4).

    4. Select one or more meshes (5). Click Select.

    5. Click Update.

                                Edit parameters in the FBX Settings to export a mesh as a .pxmesh file
    6. Once Asset Processor finishes processing the updated mesh, click OK.

    7. Close the FBX Settings window.

    For more information about the parameters in this window, see PxMesh Export Parameters.


    Click Discard if the following message appears:"You have unsaved changes. Do you want to discard those changes?".

  5. The PhysX Collision Mesh (.pxmesh file) appears in the Asset Browser.

                        Edit parameters in the FBX Settings to export a mesh as a .pxmesh

    You can now use this .pxmesh file in the following procedures:

Exporting PxMesh Automatically for Static Objects

You can set a mesh node in an FBX file to export automatically as a PhysX triangular mesh for static PhysX objects. You do this by appending _phys to the end of a mesh node name. Then, when you place the FBX file in your project's asset directory, Asset Processor automatically creates the .pxmesh file with a triangular mesh. The .pxmesh file, or PhysX Collision Mesh, appears in the Asset Browser without any further action.

If you want to export a convex mesh to use with a dynamic PhysX object, you must do so manually using the FBX Settings.

PxMesh Export Parameters

When you export a .pxmesh file from a mesh node in an FBX file, you use the FBX Settings dialog. From this dialog, you can export your .pxmesh file as a triangular mesh or a convex mesh. Triangular meshes can be used for static PhysX objects only. Convex meshes can be used for both static and dynamic PhysX objects.

Use the PhysX mesh export parameters to configure and tune the output produced by PhysX cooking later in your game.

The following example shows the default parameters to export a triangular mesh. These parameters appear when Export Mesh As Convex is not selected.

                    Triangular mesh export parameters for static objects only

The following example shows the default parameters to export a convex mesh. These parameters appear when Export Mesh As Convex is selected.

                    Convex mesh export parameters for static or dynamic objects

The triangular mesh and convex mesh export options share the following parameters. Their unique parameters are described in Triangular Mesh Export Parameters and Convex Mesh Export Parameters.

Shared PxMesh Export Parameters

Parameter Description
Name PhysX Mesh Type a name for the PhysX mesh. This name appears in the Asset Browser. You can specify up to 40 characters for the name.
Export Mesh As Convex When set, instructs the cooking process to build this mesh as convex. Required for dynamic objects but optional for static objects.
Build GPU Data When set, creates additional information required for GPU-accelerated rigid body simulation. This can increase memory usage and cooking times for convex meshes and triangular meshes. Convex hulls are created with respect to GPU simulation limitations. Vertex limit is set to 64 and vertex limit per face is internally set to 32.
Select meshes Select the meshes to include in the mesh group.

Triangular Mesh Export Parameters

                        Triangular mesh export parameters for static objects only

In addition to the shared parameters, the triangular mesh export process exposes the following parameters.

Triangular PxMesh Export Parameters

Parameter Description
Weld Vertices When set, mesh welding is performed. A clean mesh is needed; Disable Clean Mesh must not be selected.
Disable Clean Mesh When set, mesh cleaning is disabled. This makes cooking faster. When clean mesh is not performed, mesh welding is also not performed.
Force 32-Bit Indices When set, 32-bit indices are always created regardless of triangle count.
Suppress Triangle Mesh Remap Table When set, the face remap table is not created. This saves a significant amount of memory, but the SDK cannot provide the remap information for internal mesh triangles returned by collisions, sweeps, or raycasts hits.
Build Triangle Adjacencies When set, the triangle adjacency information is created. You can get the adjacency triangles for a given triangle from getTriangle.
Mesh Weld Tolerance

If mesh welding is enabled, this value controls the distance at which vertices are welded.

If mesh welding is not enabled, this value defines the acceptance distance for mesh validation.

If no two vertices are within this distance, the mesh is considered to be clean. Otherwise, a warning is issued. Ideally, you want to have a clean, welded mesh to achieve the best possible performance.

The default vertex welding uses a snap-to-grid approach. This approach effectively truncates each vertex to integer values using Mesh Weld Tolerance. Once these snapped vertices are produced, all vertices that snap to a given vertex on the grid are remapped to reference a single vertex. Following this, all triangles indices are remapped to reference this subset of clean vertices. It should be noted that the vertices that we do not alter the position of the vertices; the snap-to-grid is only performed to identify nearby vertices. The mesh validation approach also uses the same snap-to-grid approach to identify nearby vertices. If more than one vertex snaps to a given grid coordinate, we ensure that the distance between the vertices is at least meshWeldTolerance. If this is not the case, a warning is emitted.
Number of Triangles Per Leaf Mesh cooking hint for max triangles per leaf limit. Fewer triangles per leaf produces larger meshes with better runtime performance but decreased cooking performance. More triangles per leaf results in faster cooking speed and smaller mesh sizes, but with decreased runtime performance.

Convex Mesh Export Parameters

                        Convex mesh export parameters for static or dynamic objects

In addition to the shared parameters, the convex mesh export process exposes the following parameters.

Convex PxMesh Export Parameters

Parameters Description
Area Test Epsilon If the area of a triangle of the hull is below this value, the triangle is rejected. This test is performed only if Check Zero Area Triangles is set.
Plane Tolerance This value is used during hull construction. When a new point is added to the hull, it gets dropped when the point is closer to the hull than the Plane Tolerance value. The Plane Tolerance value is increased according to the hull size. If 0.0 is set, all points are accepted when the convex hull is created. This may lead to edge cases where the new points may be merged into an existing polygon and the polygons plane equation might change slightly. This can lead to failures during polygon merging phase in the hull computation. It is recommended to use the default value; however, if it is required that all points needs to be accepted or huge thin convexes are created, it might be required to lower the default value.
Use 16-bit Indices If set, uses 16-bit vertex indices in PxConvexMeshDesc::triangles or PxConvexMeshDesc::polygons. Otherwise, 32-bit vertex indices are used.
Check Zero Area Triangles Checks and removes triangles that are nearly zero-area during convex hull computation. The rejected area size is specified in PxCookingParams::areaTestEpsilon.
Quantize Input Quantizes the input vertices using the k-means clustering.
Use Plane Shifting Enables plane shifting vertex limit algorithm. Plane shifting is an alternative algorithm for the case when the computed hull has more vertices than the specified vertex limit. The default algorithm computes the full hull, and an OBB around the input vertices. This OBB is then sliced with the hull planes until the vertex limit is reached. The default algorithm requires the vertex limit to be set to at least 8, and typically produces results that are of a higher quality than that which is produced by plane shifting. When Use Plane Shifting is enabled, the hull computation stops when the vertex limit is reached. The hull planes are then shifted to contain all input vertices, and the new plane intersection points are then used to generate the final hull with the given vertex limit. Plane shifting can produce sharp edges to vertices very far away from the input cloud, and does not guarantee that all input vertices are inside the resulting hull. However, it can be used with a vertex limit as low as 4.
Shift Vertices Convex hull input vertices are shifted to be around the origin to provide better computation stability. It is recommended to provide input vertices around the origin; otherwise, use this parameter to improve numerical stability.
Gauss Map Limit Vertex limit beyond which additional acceleration structures are computed for each convex mesh. Increase the limit to reduce memory usage. Computing the extra structures does not guarantee optimal performance. There is a per-platform break-even point below which the extra structures can actually impact performance.