bevyengine/bevy

bevy_mesh

Mesh data, vertex attributes, and primitive meshing. The data layer for everything renderable that has triangles.

Purpose

bevy_mesh exists so a Bevy app can construct, manipulate, and load meshes without depending on wgpu. The actual GPU upload and rendering happen in bevy_render + the per-domain renderer crates; this crate is data-only.

The crate provides:

Mesh asset — vertex attributes, indices, primitive topology, Aabb calculation.
MeshVertexAttribute and a registry of standard attributes (POSITION, NORMAL, TANGENT, UV_0, UV_1, COLOR, JOINT_INDEX, JOINT_WEIGHT, …).
MeshBuilder primitives — algorithms that produce a Mesh from a bevy_math::Primitive (cube, sphere, capsule, plane, polygon, etc).
mikktspace tangent generation (gated behind the bevy_mikktspace feature).
Morph target data structures for blendshape animation.
Skin data for skeletal meshes.

Directory layout

crates/bevy_mesh/src/
├── lib.rs                # Re-exports
├── mesh.rs               # The big one (3,200 lines): Mesh, attributes, indices, AABB
├── primitives/           # MeshBuilder for each math primitive
├── morph.rs              # Morph targets
├── skinning.rs           # Skinned mesh joint maps
├── conversions.rs        # u8/u16/u32 buffer conversions
└── vertex.rs             # VertexBufferLayout helpers

Key abstractions

Type	File	Description
`Mesh`	`crates/bevy_mesh/src/mesh.rs`	The asset. Vertex attributes + indices + topology.
`MeshVertexAttribute`	`crates/bevy_mesh/src/mesh.rs`	A typed attribute key (`POSITION`, `NORMAL`, …).
`MeshVertexAttributeId`	`crates/bevy_mesh/src/mesh.rs`	Numeric ID used in the attribute hashmap.
`Indices`	`crates/bevy_mesh/src/mesh.rs`	`U16` or `U32` index buffer.
`PrimitiveTopology`	`crates/bevy_mesh/src/mesh.rs`	Triangle list / strip / line list / point list.
`MeshBuilder` (trait)	`crates/bevy_mesh/src/primitives/`	Trait for "this primitive can produce a mesh."
`MorphWeights`, `MorphTargets`	`crates/bevy_mesh/src/morph.rs`	Morph target machinery.
`Mesh3d`, `Mesh2d`	`crates/bevy_mesh/src/lib.rs`	Components pairing an entity with a mesh handle.

How it works

Mesh stores a hashmap of MeshVertexAttributeId → Attribute with each attribute being a Vec<...> of values. The renderer's pipeline specialization key is derived from the attribute set the mesh has, so a mesh with normals plus tangents picks a different shader permutation than one without tangents.

Mesh::compute_normals, Mesh::compute_smooth_normals, and Mesh::compute_aabb are the standard helpers. Mesh::with_generated_tangents produces tangent vectors via mikktspace.

Generating a mesh from a math primitive:

use bevy::prelude::*;
let cube: Mesh = Cuboid::new(1.0, 1.0, 1.0).mesh().build();
let sphere: Mesh = Sphere::new(0.5).mesh().ico(4).unwrap();

Integration points

Depends on: bevy_math, bevy_color, bevy_asset, bevy_image, bevy_reflect, wgpu-types (just for the topology enum), optionally mikktspace.
Depended on by: bevy_render, bevy_pbr, bevy_sprite_render, bevy_gltf, bevy_text (text mesh generation).

Entry points for modification

New primitive mesher: add a file under primitives/ and implement the Meshable trait from bevy_math plus a MeshBuilder for the result.
New attribute: add to the MeshVertexAttribute registry. Renderer code matching the attribute set has to be updated.
Custom skinning: skinning.rs.
Custom morph targets: morph.rs.