Mesh

Mesh

• indices : core::option::Option<bevy_mesh::index::Indices>
• morph_targets : core::option::Option<bevy_asset::handle::Handle<bevy_image::image::Image>>
• morph_target_names : core::option::Option<alloc::vec::Vecalloc::string::String>
• asset_usage : bevy_asset::render_asset::RenderAssetUsages

Description

A 3D object made out of vertices representing triangles, lines, or points, with "attribute" values for each vertex.

Meshes can be automatically generated by a bevy AssetLoader (generally by loading a Gltf file), or by converting a primitive using into. It is also possible to create one manually. They can be edited after creation.

Meshes can be rendered with a Mesh2d and MeshMaterial2d or Mesh3d and MeshMaterial3d for 2D and 3D respectively.

A [Mesh] in Bevy is equivalent to a "primitive" in the glTF format, for a glTF Mesh representation, see GltfMesh.

Manual creation

The following function will construct a flat mesh, to be rendered with a StandardMaterial or ColorMaterial:

# use bevy_mesh::{Mesh, Indices, PrimitiveTopology};
# use bevy_asset::RenderAssetUsages;
fn create_simple_parallelogram() -> Mesh {
    // Create a new mesh using a triangle list topology, where each set of 3 vertices composes a triangle.
    Mesh::new(PrimitiveTopology::TriangleList, RenderAssetUsages::default())
        // Add 4 vertices, each with its own position attribute (coordinate in
        // 3D space), for each of the corners of the parallelogram.
        .with_inserted_attribute(
            Mesh::ATTRIBUTE_POSITION,
            vec![[0.0, 0.0, 0.0], [1.0, 2.0, 0.0], [2.0, 2.0, 0.0], [1.0, 0.0, 0.0]]
        )
        // Assign a UV coordinate to each vertex.
        .with_inserted_attribute(
            Mesh::ATTRIBUTE_UV_0,
            vec![[0.0, 1.0], [0.5, 0.0], [1.0, 0.0], [0.5, 1.0]]
        )
        // Assign normals (everything points outwards)
        .with_inserted_attribute(
            Mesh::ATTRIBUTE_NORMAL,
            vec![[0.0, 0.0, 1.0], [0.0, 0.0, 1.0], [0.0, 0.0, 1.0], [0.0, 0.0, 1.0]]
        )
        // After defining all the vertices and their attributes, build each triangle using the
        // indices of the vertices that make it up in a counter-clockwise order.
        .with_inserted_indices(Indices::U32(vec![
            // First triangle
            0, 3, 1,
            // Second triangle
            1, 3, 2
        ]))
}

You can see how it looks like here, used in a Mesh3d with a square bevy logo texture, with added axis, points, lines and text for clarity.

Other examples

For further visualization, explanation, and examples, see the built-in Bevy examples, and the implementation of the built-in shapes. In particular, generate_custom_mesh teaches you to access and modify the attributes of a [Mesh] after creating it.

Common points of confusion

• UV maps in Bevy start at the top-left, see ATTRIBUTE_UV_0, other APIs can have other conventions, OpenGL starts at bottom-left.
• It is possible and sometimes useful for multiple vertices to have the same position attribute value, it's a common technique in 3D modeling for complex UV mapping or other calculations.
• Bevy performs frustum culling based on the Aabb of meshes, which is calculated and added automatically for new meshes only. If a mesh is modified, the entity's Aabb needs to be updated manually or deleted so that it is re-calculated.

Use with StandardMaterial

To render correctly with StandardMaterial, a mesh needs to have properly defined:

• UVs: Bevy needs to know how to map a texture onto the mesh (also true for ColorMaterial).
• Normals: Bevy needs to know how light interacts with your mesh. [0.0, 0.0, 1.0] is very common for simple flat meshes on the XY plane, because simple meshes are smooth and they don't require complex light calculations.
• Vertex winding order: by default, StandardMaterial.cull_mode is Some(Face::Back), which means that Bevy would only render the "front" of each triangle, which is the side of the triangle from where the vertices appear in a counter-clockwise order.

Functions