Scene Format Support

Open 3D Engine (O3DE) integrates Open Asset Import Library to parse 3D scene source assets. The primary 3D scene source asset format supported by O3DE is .fbx. O3DE also supports .stl, a format widely used in computer aided design (CAD) and 3D printing, and has in development support for .glTF, an open source transport format for runtime applications that is gaining popularity.

Open Asset Import Library supports many common scene formats . If you want to experiment with other formats supported by Open Asset Import Library, you can edit the o3de/Registry/sceneassetimporter.setreg settings file and add format extensions to the "SupportedFileTypeExtensions": list.

Coordinate systems

It’s important to understand O3DE’s coordinate system and the varying coordinate systems of digital content creation (DCC) applications. If the source asset uses a different coordinate system than O3DE, the asset might not be oriented correctly when loaded in O3DE Editor.

O3DE uses a right-handed coordinate system with Z as the up axis. DCC applications often use right-handed coordinate systems with Y as the up axis. In a right-handed coordinate system, positive rotation from the positive X axis to the positive Y axis is counter-clockwise.

In O3DE’s coordinate system, with the positive X axis aimed to the right, the forward axis points away from the viewer. In most DCC application coordinate systems, with the positive X axis aimed to the right, the forward axis points toward the viewer. See the illustration below for a comparison of O3DE’s coordinate system and a common DCC application coordinate system.

Most DCC applications have user settings that you can use to change their coordinate system, or options that you can use to orient the scene when it is exported, ensuring the asset is oriented correctly in O3DE. Otherwise, Scene Settings provides a Coordinate system change modifier you can use to reorient 3D scenes to O3DE’s coordinate system when source assets are processed.

World measurement units

O3DE’s base measurement unit is one cubic meter per world unit. Most DCC applications use a much smaller base measurement unit such as one cubic centimeter per world unit. This difference might result in product assets that appear microscopic in O3DE, requiring the source asset to be uniformly scaled by a factor of 100 for O3DE’s base unit of measurement.

Most DCC applications have user settings that you can use to change the DCC’s base measurement unit, or options that you can use to scale the scene when it is exported, ensuring the asset is at the proper scale in O3DE. Otherwise, the Scene Settings Coordinate system change modifier has Advanced Settings you can use to scale source assets to account for differences between your DCC application and O3DE.

Supported 3D scene data

When a 3D scene file source asset is processed, runtime optimized product assets are created and stored in the Asset Cache of your project. In most scenarios, there isn’t a one-to-one relationship between the source asset and the number of product assets that are generated. A simple mesh, for example, might produce an .azmodel, several .azlod and .pxmesh product assets, and even more .azbuffer product assets. Each of the product assets contains a subset of the scene data required for the asset.

O3DE supports a wide array of 3D scene data, however, due to the specifications of various intermediate scene formats, and the restrictions imposed by hardware resources for real-time applications, there are limitations on the data that can be processed for product assets.

The table below outlines the 3D scene data supported by O3DE and the limitations.

Important:

The data in the table below represents all of the 3D scene data supported by O3DE. Some source asset file types only support a subset of this data.

For example, popular 3D scene file formats such as .stl and .obj have limited support for certain types of mesh data and do not support animation. Other 3D scene file formats such as .bvh only support skeleton hierarchies and keyframe motion data. The various Asset Builders in O3DE only generate product assets for data that is supported by both the Asset Builder and the source asset file format.

Note:

¹ Vertices per mesh limit

The vertices per mesh limit is theoretical. The real total number of vertices is dependent on target platform hardware resources and performance.

² UV set and vertex color limits

Although the default shaders only support 2 UV sets and 1 vertex color stream, support for additional UV sets and vertex color streams can be added. Each .azmodel can have up to 12 .azbuffer product assets that store additional model data including UV sets and vertex color streams. The total number of UV sets and vertex color streams is limited by the available .azbuffer product assets. For example, suppose an .azmodel product asset has the buffers below:

• index
• position
• normals
• tangents
• bitangents
• skin weights
• joint indices

In the example asset above, 7 of the 12 available buffers contain data, leaving 5 remaining buffers available for UV sets and vertex color streams.

³ Bone influences per vertex limit

Though the max number of bone influences (skin weights) per vertex is 32, a lower default value is specified for the project in the Settings Registry. The following settings registry values can be modified to change the default skin weight settings. Allowing fewer bone influences per vertex can offer better animation performance on some target platforms.

Setting	Description	Default
/O3DE/SceneAPI/SkinRule/DefaultMaxSkinInfluencesPerVertex	The maximum number of bones that can influence any vertex in an actor mesh. Each vertex in an actor mesh can have any number of skin weights between 1 and the number specified in this registry value.	8
/O3DE/SceneAPI/SkinRule/DefaultWeightThreshold	The minimum value for a skin wight. Skin weight values below this limit are ignored.	0.001

The maximum number of bone influences and the weight threshold can be overridden on a per actor basis by adding a Skin modifier to the actor’s mesh in Scene Settings.

⁴ Cloth mesh limitations

Though any number of cloth meshes can be processed, the number and resolution of cloth meshes that O3DE can support is dependent on the target platform’s capabilities.

⁵ Physics colliders limitations

The PhysX collider Asset Builder can generate colliders from triangle meshes, primitives, or convex hulls. The generated colliders can be automatically fit to the mesh asset and complex meshes can be decomposed into convex parts. Because source asset meshes can be combined or decomposed into convex parts for collider generation, there might not be a one-to-one relationship between the number of mesh product assets and the number of PhysX collider product assets.

Though any number of PhysX colliders can be processed, the number and resolution of PhysX colliders that O3DE can support is dependent on the target platform’s capabilities. Primitive colliders provide the best performance in general.

.fbx file support

The .fbx format is portable and widely supported. It’s capable of storing complete 3D scenes with multiple assets, each composed of multiple meshes, materials, skeletons, animations, vertex attributes, and so on. Though it’s possible to include any number of assets in a single .fbx file, it’s recommended that you only include the data required for a single asset such as a character or a prop. Ensuring a .fbx source asset only generates product assets for a single character or prop can prevent issues with dependencies and asset reprocessing.

.fbx source assets can contain any of the data outlined in the table above including meshes, skeletons, animation, and PhysX meshes.

Note:

.fbx files can be ASCII or binary format. If you intend to work with automation and scripting to process .fbx source assets, you might prefer to use ASCII format .fbx files because they can be easily read and modified in script languages like Python.

.stl file support

The .stl format only supports closed, manifold meshes composed of triangles. That is, the mesh must not have open edges. Each edge must be shared by two triangles. Additional mesh data, such as UVs, materials, normals, and skin weights are not supported by .stl. Support for .stl is provided as a convenience for users of CAD and 3D printing applications.

glTF support

Feature in Progess:

glTF support is a feature that is currently in development and has known issues. You can help improve glTF support by filing new issues based on your experience using the feature and by submitting pull requests with improvements.

Refer to glTF support issues to view known issues and to file new issues for this feature.

Refer to glTF support pull requests to view open pull requests and to file new pull requests for this feature.

glTF is an open source 3D scene transport format that is gaining popularity for real-time applications. The goals of glTF are to improve interoperability between content creation and runtime applications, and to streamline the processing needed for runtime assets. glTF supports complete 3D scenes with multiple assets, each composed of multiple meshes, materials, skeletons, animations, vertex attributes, and so on.

glTF source assets can be stored in three different ways:

• Binary (.glb). The entire scene including texture assets is embedded in a single binary file with a .glb extension. This format provides the smallest and easiest to transport source assets.
• ASCII embedded (.gltf). The entire scene is stored in a single JSON formatted ASCII file with a .gltf extension. Scene data and and images are encoded in the .gltf file in Base64. This format generates a single large file, but has the benefit of providing source assets entirely encoded in a text file.
• ASCII and binary (.gltf scene description, .bin data, and texture files). The scene description is stored in a JSON formatted ASCII file with the .gltf extension. Scene data is stored in a binary file with the .bin extension. Textures are stored individually in specified image formats. This format provides reasonably small files and some unique opportunities to debug the source asset and update textures at any time, at the cost of having the source asset stored across multiple files.

Note:

At the time of this documentation, Blender provides near complete glTF support for O3DE with some issues that can be mitigated. Using ASCII and binary (.gltf scene description, .bin data, and texture files) source assets along with Visual Studio Code and the glTF Tools extension provides additional methods to debug glTF source assets.

For information on the current status of glTF support, refer to the glTF support feature request.

You can read more about .glTF at the glTF specification homepage .