Migrate meshes and materials to required components

[Jondolf]

Objective

A big step in the migration to required components: meshes and materials!

Solution

As per the selected proposal:

• Deprecate MaterialMesh2dBundle, MaterialMeshBundle, and PbrBundle.
• Add Mesh2d and Mesh3d components, which wrap a Handle<Mesh>.
• Add MeshMaterial2d<M: Material2d> and MeshMaterial3d<M: Material>, which wrap a Handle<M>.
• Meshes without a mesh material should be rendered with a default material. The existence of a material is determined by HasMaterial2d/HasMaterial3d, which is required by MeshMaterial2d/MeshMaterial3d. This gets around problems with the generics.

Previously:

commands.spawn(MaterialMesh2dBundle {
    mesh: meshes.add(Circle::new(100.0)).into(),
    material: materials.add(Color::srgb(7.5, 0.0, 7.5)),
    transform: Transform::from_translation(Vec3::new(-200., 0., 0.)),
    ..default()
});

Now:

commands.spawn((
    Mesh2d(meshes.add(Circle::new(100.0))),
    MeshMaterial2d(materials.add(Color::srgb(7.5, 0.0, 7.5))),
    Transform::from_translation(Vec3::new(-200., 0., 0.)),
));

If the mesh material is missing, previously nothing was rendered. Now, it renders a white default ColorMaterial in 2D and a StandardMaterial in 3D (this can be overridden). Below, only every other entity has a material:

Why white? This is still open for discussion, but I think white makes sense for a default material, while invalid asset handles pointing to nothing should have something like a pink material to indicate that something is broken (I don't handle that in this PR yet). This is kind of a mix of Godot and Unity: Godot just renders a white material for non-existent materials, while Unity renders nothing when no materials exist, but renders pink for invalid materials. I can also change the default material to pink if that is preferable though.

Testing

I ran some 2D and 3D examples to test if anything changed visually. I have not tested all examples or features yet however. If anyone wants to test more extensively, it would be appreciated!

Implementation Notes

• The relationship between bevy_render and bevy_pbr is weird here. bevy_render needs Mesh3d for its own systems, but bevy_pbr has all of the material logic, and bevy_render doesn't depend on it. I feel like the two crates should be refactored in some way, but I think that's out of scope for this PR.
• I didn't migrate meshlets to required components yet. That can probably be done in a follow-up, as this is already a huge PR.
• It is becoming increasingly clear to me that we really, really want to disallow raw asset handles as components. They caused me a ton of headache here already, and it took me a long time to find every place that queried for them or inserted them directly on entities, since there were no compiler errors for it. If we don't remove the Component derive, I expect raw asset handles to be a huge footgun for users as we transition to wrapper components, especially as handles as components have been the norm so far. I personally consider this to be a blocker for 0.15: we need to migrate to wrapper components for asset handles everywhere, and remove the Component derive. Also see API inconsistency with Handle as component or field of component #14124.

---

Migration Guide

Asset handles for meshes and mesh materials must now be wrapped in the Mesh2d and MeshMaterial2d or Mesh3d and MeshMaterial3d components for 2D and 3D respectively. Raw handles as components no longer render meshes.

Additionally, MaterialMesh2dBundle, MaterialMeshBundle, and PbrBundle have been deprecated. Instead, use the mesh and material components directly.

Previously:

commands.spawn(MaterialMesh2dBundle {
    mesh: meshes.add(Circle::new(100.0)).into(),
    material: materials.add(Color::srgb(7.5, 0.0, 7.5)),
    transform: Transform::from_translation(Vec3::new(-200., 0., 0.)),
    ..default()
});

Now:

commands.spawn((
    Mesh2d(meshes.add(Circle::new(100.0))),
    MeshMaterial2d(materials.add(Color::srgb(7.5, 0.0, 7.5))),
    Transform::from_translation(Vec3::new(-200., 0., 0.)),
));

If the mesh material is missing, a white default material is now used. Previously, nothing was rendered if the material was missing.

The WithMesh2d and WithMesh3d query filter type aliases have also been removed. Simply use With<Mesh2d> or With<Mesh3d>.

[Jondolf]

Hmm one potential problem with the HasMaterial2d/HasMaterial3d approach is that the default material is only used before the first material insertion. If you add a material and then remove it, the default/placeholder material won't be used anymore. We'd need a MaterialCount component that gets incremented/decremented as materials are added/removed, and manage the existence of the marker component based on that.

Should I add this, or is it desired behavior that the placeholder material is only shown before a material is added for the first time?

[tim-blackbird]

Reviewed bevy_pbr and bevy_render, still have to check bevy_sprite and the examples

[NiseVoid]

Hmm one potential problem with the HasMaterial2d/HasMaterial3d approach is that the default material is only used before the first material insertion. If you add a material and then remove it, the default/placeholder material won't be used anymore. We'd need a MaterialCount component that gets incremented/decremented as materials are added/removed, and manage the existence of the marker component based on that.

Doesn't seem like the biggest issue at least, the counter would feel more consistent, and not be very hard to make with required components and hooks. But if our plan going forward is to merge Mesh and MeshMaterial in some way that problem would also fix itself, tho that's definitely a more complex topic considering we have features like multiple materials per mesh and whatnot 🤔