3D objects not displaying

This page will list some common issues that you may encounter, if you are trying to spawn a 3D object, but cannot see it on the screen.

Missing Vertex Attributes

Make sure your Mesh includes all vertex attributes required by your shader/material.

Bevy's default PBR StandardMaterial requires all meshes to have:

  • Positions
  • Normals
  • UVs (even if there are no textures / just a solid color)
  • Tangents (if using normal maps, otherwise not required)

If you are generating your own mesh data, make sure to include all of the above.

If you are loading it from asset files, make sure they include everything that is needed. In particular, if you are using normal maps, make sure to include Tangents when creating your GLTF files.

Incorrect usage of Bevy GLTF assets

Refer to the GLTF page to learn how to correctly use GLTF with Bevy.

GLTF files are complex. They contain many sub-assets, represented by different Bevy types. Make sure you are using the correct thing.

Make sure you are spawning a GLTF Scene, or using the correct Mesh and StandardMaterial associated with the correct GLTF Primitive.

If you are using an asset path, be sure to include a label for the sub-asset you want:

asset_server.load("my.gltf#Scene0");

If you are spawning the top-level Gltf master asset, it won't work.

If you are spawning a GLTF Mesh, it won't work.

Unsupported GLTF

Bevy does not fully support all features of the GLTF format and has some specific requirements about the data. Not all GLTF files can be loaded and rendered in Bevy. Unfortunately, in many of these cases, you will not get any error or diagnostic message.

Commonly-encountered limitations:

  • Textures embedded in ascii (*.gltf) files (base64 encoding) cannot be loaded. Put your textures in external files, or use the binary (*.glb) format.
  • Mipmaps are only supported if the texture files (in KTX2 or DDS format) contain them. The GLTF spec requires missing mipmap data to be generated by the game engine, but Bevy does not support this. If your assets are missing mipmaps, textures will look grainy/noisy.
  • Bevy's renderer requires all meshes/primitives to have per-vertex positions, UVs, and normals. Make sure all of this data is included.
  • Meshes/primitives without textures (if the material is just a solid color) must still include UVs regardless. Bevy will not render meshes without UVs.
  • When using normal maps in your material, tangents must also be included in the mesh. Assets with normal maps but without tangents are valid; other software would typically autogenerate the tangents if they are missing, but Bevy does not support this yet. Be sure to tick the checkbox for including tangents when exporting.
  • Spot lights are not supported. Bevy currently only has Point lights and Directional lights.

This list is not exhaustive. There may be other unsupported scenarios that I did not know of or forgot to include here. :)

Unoptimized / Debug builds

Maybe your asset just takes a while to load? Bevy is very slow without compiler optimizations. It's actually possible that complex GLTF files with big textures can take over a minute to load and show up on the screen. It would be almost instant in optimized builds. See here.

Vertex Order and Culling

By default, the Bevy renderer assumes Counter-Clockwise vertex order and has back-face culling enabled.

If you are generating your Mesh from code, make sure your vertices are in the correct order.