用途
该技能用于在 Bevy 引擎中为网格(mesh)提供 PBR 表面。当网格需要一个 PBR 表面时应加载本技能;自定义着色器扩展点由 bevy-shaders 负责,光照由 bevy-3d-lighting 负责。目标版本为 Bevy 0.20+。
主要能力
- 类型:
StandardMaterial(包含功能说明与DistanceFog)。 - 扩展:
ExtendedMaterial,位于 pbr 页面。 - 提及 StandardMaterial 纹理的特性:
pbr_anisotropy_texture、pbr_multi_layer_material_textures、pbr_specular_textures、pbr_transmission_textures。书写字段前请查阅结构体页面确认字段名。 - 插件:
bevy_pbr提供 PBR 渲染,属于 3D 渲染集合的一部分。
使用方式
表面选择
| 需求 | Bevy 惯用法 |
|---|---|
| PBR 表面 | 在 MeshMaterial3d 上使用 StandardMaterial,配合 base_color、metallic 和 perceptual_roughness。 |
| 在该表面上附加额外着色器数据 | ExtendedMaterial<StandardMaterial, E>,其中 E: MaterialExtension。 |
| 透明 | alpha_mode:AlphaMode::Mask 用于抠图,AlphaMode::Blend 用于玻璃。 |
依赖
[dependencies]
bevy = "0.20"
生成带金属材质的网格
网格组件是 Mesh3d,材质组件是 MeshMaterial3d<StandardMaterial>。
fn spawn_metal(
mut commands: Commands,
mut meshes: ResMut<Assets<Mesh>>,
mut materials: ResMut<Assets<StandardMaterial>>,
) {
let mesh = meshes.add(Cuboid::new(1.0, 1.0, 1.0));
let material = materials.add(StandardMaterial {
base_color: Color::srgb(0.75, 0.15, 0.12),
metallic: 1.0,
perceptual_roughness: 0.25,
reflectance: 0.5,
..default()
});
commands.spawn((Mesh3d(mesh), MeshMaterial3d(material), Transform::default()));
}
抠图与玻璃
抠图植被会丢弃遮罩阈值以下的片段;玻璃使用 alpha 混合与半透明基色。
fn cutout_leaf(image: Handle<Image>) -> StandardMaterial {
StandardMaterial {
base_color_texture: Some(image),
alpha_mode: AlphaMode::Mask(0.5),
diffuse_transmission: 0.4,
cull_mode: None,
..default()
}
}
fn glass() -> StandardMaterial {
StandardMaterial {
base_color: Color::srgba(0.7, 0.85, 1.0, 0.25),
alpha_mode: AlphaMode::Blend,
metallic: 0.0,
perceptual_roughness: 0.05,
..default()
}
}
运行时重染色
共享资产保持为唯一事实来源。运行时染色会把该句柄的材质克隆成新资产,使其他网格保留原材质。
fn tint_one_mesh(
mut materials: ResMut<Assets<StandardMaterial>>,
mesh: Query<&MeshMaterial3d<StandardMaterial>>,
) {
let Ok(handle) = mesh.single() else {
return;
};
let Some(source) = materials.get(handle.id()) else {
return;
};
let mut tinted = source.clone();
tinted.base_color = Color::srgb(0.2, 0.45, 0.9);
let _unique = materials.add(tinted);
}
ExtendedMaterial
ExtendedMaterial 保留全部 StandardMaterial 字段并添加扩展数据。生成前需注册具体材质类型。
use bevy::pbr::{ExtendedMaterial, MaterialExtension};
use bevy::render::render_resource::AsBindGroup;
#[derive(Asset, AsBindGroup, TypePath, Clone, Default)]
struct Wear {
#[uniform(100)]
amount: f32,
}
impl MaterialExtension for Wear {}
fn register_wear(app: &mut App) {
app.add_plugins(MaterialPlugin::<ExtendedMaterial<StandardMaterial, Wear>>::default());
}
fn spawn_worn(
mut commands: Commands,
mut meshes: ResMut<Assets<Mesh>>,
mut materials: ResMut<Assets<ExtendedMaterial<StandardMaterial, Wear>>>,
) {
let mesh = meshes.add(Cuboid::new(1.0, 1.0, 1.0));
let material = materials.add(ExtendedMaterial {
base: StandardMaterial {
base_color: Color::srgb(0.4, 0.35, 0.3),
perceptual_roughness: 0.8,
..default()
},
extension: Wear { amount: 0.6 },
});
commands.spawn((Mesh3d(mesh), MeshMaterial3d(material)));
}
适用场景
- 为网格提供 PBR 表面(金属、粗糙度、反射率)。
- 通过
alpha_mode实现植被抠图或玻璃透明。 - 在同一共享材质基础上做运行时克隆与染色。
- 通过
ExtendedMaterial在标准 PBR 表面附加自定义着色器数据。
限制
- 本技能只命名有文档记录的 Bevy crate 与模块。
- 不得使用本技能未命名的材质字段:未命名字段会随 Bevy 版本变化,编译器是校验手段。
- 不得虚构 API 或未命名的第三方 crate 作为解决方案。
- 文档 URL 不要固定
/0.20.0/:链接保持latest,0.20 目标只需在正文中说明一次。 - 不要从未排序的两个系统中可变查询同一组件:除非用
.chain()排序,调度器会并行运行系统。 - 不要在此处虚构物理、导航、网络或 XR crate。
参考
- Assets:https://bevy.org/assets/
- Examples:https://github.com/bevyengine/bevy/tree/latest/examples#examples
- 3D examples:https://github.com/bevyengine/bevy/tree/latest/examples/3d
- ECS:https://bevy.org/learn/quick-start/getting-started/ecs/
- Plugins:https://bevy.org/learn/quick-start/getting-started/plugins/
相关技能
前置:
- bevy-master:https://github.com/thedivergentai/Game-Dev-Agentic-Skills/blob/main/skills/bevy-master/SKILL.md
- bevy-ecs-composition:https://github.com/thedivergentai/Game-Dev-Agentic-Skills/blob/main/skills/bevy-ecs-composition/SKILL.md
- bevy-shaders:https://github.com/thedivergentai/Game-Dev-Agentic-Skills/blob/main/skills/bevy-shaders/SKILL.md
- bevy-3d-lighting:https://github.com/thedivergentai/Game-Dev-Agentic-Skills/blob/main/skills/bevy-3d-lighting/SKILL.md
互补:暂无。 下游 / 消费者:暂无。 Master:bevy-master(Bevy 路由器)。