NEOLearn

Meshes

Draw 3D geometry with Mesh3d: the built-in shapes, meshes from glTF files, building a mesh from vertices and changing one at runtime.

Updated October 20, 2026

On this page

A mesh is the shape of an object: vertices, the triangles between them and per-vertex data such as normals and texture coordinates. To draw one, put a Mesh3d holding a mesh handle on an entity, together with a material (see Materials).

Rust
fn setup(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<StandardMaterial>>,
) {
    commands.spawn((
        Mesh3d(meshes.add(Sphere::new(0.5).mesh().uv(32, 18))),
        MeshMaterial3d(materials.add(Color::srgb(0.3, 0.6, 0.3))),
        Transform::from_xyz(0.0, 1.0, 0.0),
    ));
}

Mesh3d requires a Transform and visibility, so the entity is placed in the world and can be hidden. A mesh with no material component isn't drawn.

Built-in shapes#

The engine's math shapes turn into meshes. meshes.add(shape) uses default settings; shape.mesh() returns a builder with options.

ShapeBuilder options
Cuboid::new(x, y, z)
Sphere::new(radius).mesh().uv(sectors, stacks), or .mesh().ico(subdivisions) (returns a Result)
Plane3d::default().mesh().size(w, h), .subdivisions(n)
Capsule3d::new(radius, length)
Cylinder::new(radius, height), Cone, ConicalFrustum
Torus::default(), Tetrahedron::default()
Segment3d, Polyline3dLines.
2D shapes (Circle, Rectangle, RegularPolygon, Triangle2d, Annulus, Capsule2d, Ellipse)Flat meshes in the XY plane.
Extrusion::new(shape_2d, depth)Gives a 2D shape thickness. shape.to_ring(thickness) makes a hollow outline first.

Example: cargo run --example 3d_shapes.

Meshes from files#

Most meshes come from glTF files made in a modelling tool. Load the whole file as a scene with WorldAssetRoot, which spawns its nodes, meshes, materials and lights as children:

Rust
fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn(WorldAssetRoot(
        asset_server.load(GltfAssetLabel::Scene(0).from_asset("models/FlightHelmet/FlightHelmet.gltf")),
    ));
}

To load a single mesh primitive instead, use GltfAssetLabel::Primitive { mesh: 0, primitive: 0 }. See glTF for the labels and loader settings.

Build a mesh#

Build a mesh from vertex attributes and indices:

Rust
use neo::asset::RenderAssetUsages;
use neo::mesh::Indices;
use neo::render::render_resource::PrimitiveTopology;

fn quad() -> Mesh {
    Mesh::new(PrimitiveTopology::TriangleList, RenderAssetUsages::default())
        .with_inserted_attribute(
            Mesh::ATTRIBUTE_POSITION,
            vec![[-0.5, 0.0, -0.5], [0.5, 0.0, -0.5], [0.5, 0.0, 0.5], [-0.5, 0.0, 0.5]],
        )
        .with_inserted_attribute(Mesh::ATTRIBUTE_NORMAL, vec![[0.0, 1.0, 0.0]; 4])
        .with_inserted_attribute(
            Mesh::ATTRIBUTE_UV_0,
            vec![[0.0, 0.0], [1.0, 0.0], [1.0, 1.0], [0.0, 1.0]],
        )
        .with_inserted_indices(Indices::U32(vec![0, 3, 1, 1, 3, 2]))
}

Triangles wind counter-clockwise when seen from the front; back faces are culled by default.

AttributeTypeWhat it's for
ATTRIBUTE_POSITION[f32; 3]Required.
ATTRIBUTE_NORMAL[f32; 3]Lighting. with_computed_normals() (or compute_flat_normals, compute_smooth_normals) fills it in.
ATTRIBUTE_UV_0, ATTRIBUTE_UV_1[f32; 2]Texture coordinates; the second set is for lightmaps.
ATTRIBUTE_TANGENT[f32; 4]Normal maps. with_generated_tangents() computes them.
ATTRIBUTE_COLOR[f32; 4]Vertex colours, multiplied with the material's base colour. Example: vertex_colors.
ATTRIBUTE_JOINT_INDEX, ATTRIBUTE_JOINT_WEIGHTSkinning, filled in by the glTF loader.

Your own attributes need a custom material and shader; see cargo run --example custom_vertex_attribute.

Keep a mesh editable#

RenderAssetUsages says where the mesh's data lives. RENDER_WORLD alone uploads it to the GPU and frees the CPU copy, which saves memory. Keep MAIN_WORLD too if you change the mesh later:

Rust
fn ripple(mesh: Single<&Mesh3d>, mut meshes: ResMut<Assets<Mesh>>, time: Res<Time>) {
    let Some(mut mesh) = meshes.get_mut(&mesh.0) else { return };
    if let Some(VertexAttributeValues::Float32x3(positions)) =
        mesh.attribute_mut(Mesh::ATTRIBUTE_POSITION)
    {
        for p in positions.iter_mut() {
            p[1] = (p[0] * 4.0 + time.elapsed_secs()).sin() * 0.1;
        }
    }
}

VertexAttributeValues is in neo::mesh. Example: cargo run --example generate_custom_mesh.

Instancing#

Entities that share the same mesh handle and the same material handle are drawn together in one draw call automatically. Reuse handles instead of adding a new mesh or material per entity:

Rust
let mesh = meshes.add(Cuboid::default());
let material = materials.add(Color::WHITE);
for x in 0..100 {
    commands.spawn((
        Mesh3d(mesh.clone()),
        MeshMaterial3d(material.clone()),
        Transform::from_xyz(x as f32 * 1.5, 0.0, 0.0),
    ));
}

Example: cargo run --example automatic_instancing.

Wireframes#

WireframePlugin (in neo::pbr::wireframe) draws mesh edges, for every mesh (WireframeConfig { global: true, .. }) or per entity (Wireframe). It works on desktop GPUs (Vulkan, Metal, DX12), not in web builds. Example: cargo run --example wireframe.

Next steps#