As this page is outdated, please refer to Bevy's official migration guides while reading, to cover the differences: 0.11 to 0.12, 0.12 to 0.13.

I apologize for the inconvenience. I will update the page as soon as I find the time.

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 visibility components on parent

If your entity is in a hierarchy, all its parents need to have visibility components. It is required even if those parent entities are not supposed to render anything.

Fix it by inserting a VisibilityBundle:

#![allow(unused)]
fn main() {
commands.entity(parent)
    .insert(VisibilityBundle::default());
}

Or better, make sure to spawn the parent entities correctly in the first place. You can use a VisibilityBundle or SpatialBundle (with transforms) if you are not using a bundle that already includes these components.

Too far from camera

If something is further away than a certain distance from the camera, it will be culled (not rendered). The default value is 1000.0 units.

You can control this using the far field of PerspectiveProjection:

#![allow(unused)]
fn main() {
commands.spawn(Camera3dBundle {
    projection: Projection::Perspective(PerspectiveProjection {
        far: 10000.0, // change the maximum render distance
        ..default()
    }),
    ..default()
});
}

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

Some others that may be required:

• UVs (if using textures in the material)
• Tangents (only if using normal maps, otherwise not required)

If you are generating your own mesh data, make sure to provide everything you need.

If you are loading meshes from asset files, make sure they include everything that is needed (check your export settings).

If you need Tangents for normal maps, it is recommended that you include them in your GLTF files. This avoids Bevy having to autogenerate them at runtime. Many 3D editors (like Blender) do not enable this option by default.

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:

let handle_scene: Handle<Scene> = 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 yet. If your assets are missing mipmaps, textures will look grainy/noisy.

This list is not exhaustive. There may be other unsupported scenarios that I did not know of or forgot to include 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.

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.