Meshes
Draw 3D geometry with Mesh3d: the built-in shapes, meshes from glTF files, building a mesh from vertices and changing one at runtime.
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).
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.
| Shape | Builder 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, Polyline3d | Lines. |
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:
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:
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.
| Attribute | Type | What 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_WEIGHT | Skinning, 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:
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:
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.