Manual
Manual
Meshes and materials
An entity is drawn in 3D by a mesh, its shape, and a material, its surface. This page covers the Mesh 3D and Mesh Material 3D sections of the Inspector, the engine's six 3D objects, materials as .mat files and how the Inspector edits them, giving one entity a surface of its own, and meshes and materials your code makes as the game plays.
Meshes, materials and the entities drawn with them
A mesh and a material are assets, not components. An entity holds the mesh in its Mesh 3D section and the material in its Mesh Material 3D section, and many entities can hold the same ones: a thousand trees are a thousand entities, one mesh and one material. Because they share it, changing a material changes every entity drawn with it, at once.
A mesh comes from one of three places: the engine's own shapes, a model you imported (see Models), or your code. A material is Bevy's own lit surface, described by numbers and five textures, or a material running one of your game's shaders (see Shaders). Either kind can be a material file in your assets, a model's own material, or one your code makes.
3D objects
Entity ▸ 3D Object, or the same menu under the Hierarchy's + and its right-click menu, makes an entity drawn with one of the engine's six shapes:
| Object | Its shape |
|---|---|
| Cube | One unit along each side |
| Sphere | One unit across |
| Capsule | One unit across and two high |
| Cylinder | One unit across and two high |
| Plane | Ten units along each side, flat on X and Z, facing up |
| Quad | One unit along each side, flat on X and Y, facing +Z |
Each is named after its shape, centered on its origin, and drawn with a white surface of its own, so changing one cube's surface in the Inspector changes that cube alone. Every world has these shapes, a built game's too, and a scene names them by their names.
Mesh 3D
The mesh an entity is drawn as, and whether it casts and receives shadows.
| Field | What it does |
|---|---|
| Mesh | The mesh: one of the engine's shapes by its name, or a model's, shown as model › mesh. |
| Cast Shadows | Whether the mesh casts shadows from the lights that cast them. On at first. |
| Receive Shadows | Whether shadows fall on the mesh. On at first. |
Drop a model from the Project panel onto the Mesh slot for its first mesh, or unfold the model's tile with its arrow and drop one of its meshes. The button beside the slot lists the engine's shapes under Built In and every imported model's meshes under Models. What you pick is given to every entity picked, each keeping the material it is drawn with, and Ctrl+Z takes it back.
A Mesh 3D added with Add Component holds no mesh until you give it one. Giving an entity a mesh also gives it a Transform, since Bevy's mesh component requires one: an entity that had none is placed at the origin.
Mesh Material 3D
The material an entity is drawn with. The section has one slot, Material, and the right end of its header says which kind the material is: Standard Material, Bevy's own surface, or Shader Material, one running a shader of your game's.
To give entities a material file:
- drop it onto the Material slot, or pick it with the slot's button, which lists every material file in your assets;
- drop it onto an entity's row in the Hierarchy;
- drop it onto the Scene panel, where it goes to whatever is drawn under the pointer.
The slot also takes one of a model's materials, unfolded from the model's tile in the Project panel. A material dropped onto an entity with neither a Mesh 3D nor a Mesh Material 3D leaves it as it is.
What a material holds, at the foot of the Inspector
Below an entity's components, the Inspector shows the material it is drawn with, headed by the material's name: a material file by its file name, a model's as model › Material0, and one of an entity's own by its number. A line under the name says where it comes from. Its rows are the same as a material file's (see The material Inspector), and an edit there changes the material itself, so every entity drawn with it changes. A material file edited there is saved to its file. Its texture slots are shown as the images they hold; to change them, pick the material file in the Project panel.
Material files
A material file is a .mat in your assets. In the Project panel, choose Material in the + button's menu, or New Material in the right-click menu, to make NewMaterial.mat in the folder shown: Bevy's own surface, white, with its name ready to type. Pick it to edit it in the Inspector.
The file is JSON, so you can read it and diff it in version control. shader says what the material runs: standard for Bevy's own surface, or a file in your game's shaders folder. values holds what you changed, by the names the shader gives them, and textures the images in its slots, by their paths. Each file it names is named by its identity too, under ids, so an image or a shader you move or rename is still found.
{
"abyssMaterial": 2,
"ids": {
"base_color": "6d33cf113bfc4cd183855291b38be3c0"
},
"shader": "standard",
"textures": {
"base_color": "textures/wall.png"
},
"values": {
"base_color": [0.58, 0.04, 0.03, 1],
"perceptual_roughness": 0.5
}
}What the file leaves out starts as its shader says. One material file is one material: everything drawn with the file shares it, and a scene names it by its path and identity.
- Edits are saved as you make them, each one Ctrl+Z, with no Apply. They are part of the file, not of the scene, so they last after Stop, and saving the scene does not save them.
- A file changed by another program, such as a text editor or a checkout, is read again, and everything drawn with it changes.
- An image the file names that cannot be read is left out: the material is drawn without it, the log says so once, and it is drawn with the image again once the image is there.
- A built game reads each material packed into a binary form of the engine's own, and no JSON. See Build and run your game.
A model's materials can be written out as material files with Extract Materials in its import settings, and a material file can take the place of one of a model's materials; see Models.
The material Inspector
Picked in the Project panel, a material file shows its name, then a Shader list: Standard, Bevy's own surface, first, then each shader in your game's shaders folder. Picking another shader keeps in the file what the new shader does not take, so picking the old one again brings those values back.
Bevy's own surface
A material running Standard shows these rows:
| Field | What it does |
|---|---|
| Unlit | Ignores the lights: the surface is drawn its color as it is, even in a scene with no light. |
| Double Sided | Draws the back faces of its triangles too, rather than leaving them out. |
| Flip Normal Map Y | Reads the normal map's green channel the other way round, as some programs write it. |
| Transparency | How it is drawn over what is behind it; see Transparency. |
| Base Color | Its color, with alpha. The base color texture is multiplied by it. |
| Emissive | Light the surface gives out whatever lights it, as a color that can be brighter than white. The emissive texture is multiplied by it. |
| Metallic | 0 for a non-metal, 1 for a metal. |
| Perceptual Roughness | 0 for a mirror, 1 for chalk. |
| Reflectance | How much light a non-metal reflects when seen head on. 0.5, the default, is about 4%. |
| Alpha Cutoff | With Transparency at Mask, the alpha below which a pixel is left out. |
Under them are its five texture slots. Drop an image from the Project panel onto a slot, or pick one with its button; None empties it. A slot naming an image your project does not have says Missing, with the file's name.
| Slot | What the image holds |
|---|---|
| Base Color Texture | The surface's color |
| Emissive Texture | The light it gives out |
| Metallic Roughness Texture | Roughness in green and metalness in blue |
| Normal Map Texture | Its normals, for detail the mesh does not have |
| Occlusion Texture | In red, how much of the ambient light reaches each place |
An image used as a normal map should be imported as one; see Textures.
A material running your shader
A material running one of your game's shaders shows Double Sided and Transparency, then a row for each value the shader takes, by the name the shader gives it, and a slot for each texture it binds. A value whose name has color in it is a color swatch; a 4×4 matrix is four rows. See Shaders.
Transparency
| Choice | How the surface is drawn |
|---|---|
| Opaque | Whole, whatever its alpha says. The default. |
| Mask | Each pixel either whole or left out, by its alpha against Alpha Cutoff. For leaves, fences and cut-outs. |
| Blend | Blended over what is behind it by its alpha. |
| Premultiplied | Blended, its color already multiplied by its alpha. |
| AlphaToCoverage | Its alpha turned into how many of a pixel's samples it covers. Needs the camera's multisampling. |
| Add | Added to what is behind it, as light is. |
| Multiply | Multiplied into what is behind it, as a tint is. |
A material file keeps it among its values as "alpha_mode", written in lowercase with underscores, such as "blend" or "alpha_to_coverage", and Double Sided as "double_sided": true.
How a scene keeps what an entity is drawn with
A scene writes an entity's mesh and material together. A mesh from a model is written by its path, such as models/pyramid.gltf#Mesh0/Primitive0, an engine shape by its name, and a material file by its path and identity. A surface of an entity's own, such as a 3D object's white one changed in the Inspector, is written into the scene as its values. A material running one of your shaders is kept only as the material file it came from. An entity with a mesh and no material, or a material and no mesh, keeps neither when the scene is saved, so give it both.
Materials from code
Systems reach the world's assets through context.Assets, at once rather than as commands, and safely from systems that run in parallel. Giving an asset to an entity changes the entity, so it is a command: context.Commands.SetMesh and context.Commands.SetMaterial. A flow uses flow.Assets, and a plugin's Build the same methods on schedule.World.
Load and make materials
A material file, or a model's material, loads by its key, once it is ticked Addressable (see Assets, identities and addresses):
MaterialId red = context.Assets.LoadMaterial(Addresses.Materials.Red);MaterialId wood = context.Assets.LoadMaterial(Addresses.Models.Door.Materials.Wood);The id is yours at once and the material arrives in the background, drawn white until it lands. context.Assets.StateOf(red) says whether it is Loading, Loaded or Failed.
To make one of Bevy's surfaces, start from MaterialSpec.Default, white and fairly rough, and change what you want. A zeroed MaterialSpec is black and fully transparent. Its colors are linear.
MaterialId gold = context.Assets.CreateMaterial(MaterialSpec.Default with{ Red = 1f, Green = 0.77f, Blue = 0.34f, Metallic = 1f, PerceptualRoughness = 0.3f,});
MaterialId glass = context.Assets.CreateMaterial(MaterialSpec.Colored(0.6f, 0.8f, 1f, 0.3f) with{ Transparency = AlphaKind.Blend,});A texture slot holds an image's id, such as spec with { BaseColorTexture = image.Value }, or spec.WithTexture(image.Value) for the base color. An image can be loaded by its key or made from pixels; see Textures. A material running one of your shaders is made from the shader, CreateMaterial(shaderId); see Shaders.
Give an entity a mesh and a material
A system that gives meshes or materials declares it in its structural access, AndSetMesh or AndSetMaterial:
schedule.Add("Gild", [crown.Read()], context =>{ foreach (Chunk chunk in context.Chunks) { foreach (ulong entity in chunk.Entities) { context.Commands.SetMaterial(entity, gold); // keeps its mesh } }}, structural: StructuralAccess.None.AndSetMaterial);SetMesh(entity, mesh, material) gives both, and has a form that takes many entities at once. A material of default keeps the material the entity has and changes only its mesh. An id that names no asset is an error when the command applies, rather than an entity silently drawn with nothing.
Change a material
SpecOf reads what one of Bevy's surfaces is, and UpdateMaterial changes it, for every entity drawn with it:
MaterialSpec now = context.Assets.SpecOf(gold);context.Assets.UpdateMaterial(gold, now with { EmissiveRed = 2f, EmissiveGreen = 1.4f, EmissiveBlue = 0.5f });A material loaded from a file stops being the file's once you change it from code: the file is not written, and a scene saved afterward keeps the new values rather than the file's path.
context.Assets.MaterialOf(entity) is the material an entity is drawn with, and MeshOf(entity) its mesh and material together, or null where it has none.
One entity's own surface
Since every entity drawn with a material shares it, give one entity a copy to make it look different. CopyMaterial makes a material that starts as the original is, textures and all, sharing its images:
schedule.Add("Tint one", [tint.Read()], context =>{ foreach (Chunk chunk in context.Chunks) { foreach (ulong cube in chunk.Entities) { MaterialId mine = context.Assets.CopyMaterial(context.Assets.MaterialOf(cube)!.Value); context.Assets.UpdateMaterial(mine, context.Assets.SpecOf(mine) with { Red = 1f, Green = 0.2f, Blue = 0.2f }); context.Commands.SetMaterial(cube, mine); // its mesh stays as it is context.Assets.Release(mine); // the cube keeps it, and it goes when the cube does } }}, structural: StructuralAccess.None.AndSetMaterial);A copy of a material file's material is that file's too until you change it.
Letting go
An asset your code made or loaded stays while anything holds it: your load, an entity drawn with it, a material using an image. context.Assets.Release gives your hold back, and the asset goes once nothing holds it; from then on its id is refused. So the usual way is to make a material, give it to entities, and release it at once, as above: the entities keep it, and it goes with the last of them.
When you stop the game in the editor, what the game made is let go of, and what it let go of of the scene's is kept again.
Meshes from code
Make a mesh
A mesh is vertex data from your own arrays, passed as spans in one call. Positions and Indices are required: x, y and z for each corner, and three corners for each triangle, wound counterclockwise as seen from its front. Normals (x, y, z), Uvs (u, v) and colors are optional, but each one given has one entry for every corner. A lit surface needs normals, and a texture needs texture coordinates.
float[] positions = [0, 0, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0];float[] normals = [0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1];float[] uvs = [0, 1, 1, 1, 1, 0, 0, 0];uint[] indices = [0, 1, 2, 0, 2, 3];
MeshId square = context.Assets.CreateMesh(new MeshData{ Positions = positions, Normals = normals, Uvs = uvs, Indices = indices,});context.Commands.SetMesh(entity, square, gold);context.Assets.Release(square);The data is checked as you pass it: a count that does not match, or an index past the last corner, is refused there and then, naming what is wrong.
The engine's own shapes are there by name, in any world: context.Assets.MeshByName("Cube"), and likewise Sphere, Capsule, Cylinder, Plane and Quad.
Replace a mesh as the game plays
UpdateMesh gives a mesh you made new data, whole, as many corners and triangles as it now has, under the same MeshId. Every entity drawing it draws the new data from the next frame, with its bounds worked out again, and a Mesh Collider 3D made of it is made again at the next physics step. That is what a world of blocks does as a chunk changes:
context.Assets.UpdateMesh(chunk, new MeshData { Positions = positions, Normals = normals, Indices = indices });uint times = context.Assets.MeshRevision(chunk); // how many times it has been replacedIt can be called from any system, as CreateMesh can. A mesh read from a model, and the engine's own shapes, which every cube shares, are refused: make a mesh of your own instead.
Vertex colors
A mesh can carry a color for each corner, linear, which Bevy's surface multiplies its color by, as it does for a model's vertex colors: a block world's corner shading and light levels, for example. Give them as Colors, four floats a corner from 0 to 1, or as Colors32, four bytes a corner, red first in memory (0xAABBGGRR as a number), a quarter of the size. Give one or the other, not both.
context.Assets.UpdateMesh(chunk, new MeshData { Positions = positions, Normals = normals, Colors32 = shade, Indices = indices });A shader of your own reads them as in.color where VERTEX_COLORS is defined.
In the Scripting API
- AssetAccess: meshes and materials loaded, made, changed, copied and let go of from a system.
- CommandBuffer and StructuralAccess:
SetMeshandSetMaterial, and the access a system declares for them. - MaterialSpec and AlphaKind: Bevy's own surface as numbers, and how it is drawn over what is behind it.
- MeshData: the vertex data of a mesh made by code.
- MeshId and MaterialId: a mesh and a material, as ids your code keeps.
- MaterialAddress and MeshAddress: the keys a material and a model's mesh are loaded by.
- MaterialFiles: the
.matfile.
