bevy-3d-materials

用途

当网格需要 PBR 表面时加载本技能。自定义着色器扩展点位于 bevy-shaders，光照位于 bevy-3d-lighting。

ECS 形态

类型：StandardMaterial（feature blurbs 与 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"

生成一个带金属 StandardMaterial 的网格。网格组件是 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 保留所有 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)));
}

专家知识增量

目标：Bevy 0.20+。

核心 ECS 类型：Component、Resource、Query、Commands、Startup、Update、Fixed / FixedMain（bevy::time）、.chain()、Plugin、DefaultPlugins、MinimalPlugins。消息与观察者是一个归属槽位，其 API 见 bevy-events-messaging。除非 .chain() 对冲突的系统排序，否则系统并行运行。

谁拥有状态

部分	拥有者	谁可以修改	调度
单个实体上的数据	Component	一个系统通过 Query	Update 或 FixedMain
整个应用的一个值	Resource	一个系统	Startup 插入，然后读取它的调度
生成	Commands	生成的系统	Startup 用于初始世界；后续调度用于运行时生成
不能竞态的顺序	.chain()	仅被链式连接的系统	同一调度
插件边界	Plugin	build 注册系统和资源	应用运行之前

借用规则：两个都可变查询同一组件的系统必须排序（.chain()）或拆分，使只有一个写入。不相关的系统保持并行。这是 ECS 页面规则，不是对系统集 API 的猜测。

决策

如果你需要	这样做	不要
每实体数据	Component + Query	存储在世界之外的普通结构体
应用级配置或时钟	Resource	把值复制到每个实体上
稳定的模拟步长	FixedMain 和 Fixed 时钟	把模拟绑定到原始帧 Update
启动生成	Startup 中的 Commands	从渲染系统生成
非共享状态的跨系统通知	bevy-events-messaging 中的消息或观察者槽位	在本文件中发明新的事件类型
文档集合之外的 API	先查看官方文档	编造的 crate 或 API

加载 references/ecs-ownership.md 查看归属表。

禁止事项

不要在文档 URL 中固定 /0.20.0/。原因：链接保持在最新版；0.20 目标只在正文中声明一次。
不要从两个无序系统可变查询同一组件。原因：除非 .chain() 排序，否则调度并行运行系统。
不要在此发明物理、导航、网络或 XR crate。原因：本技能只命名有文档的 Bevy crate 和模块。
不要使用本技能未命名的材质字段。原因：未命名字段在 Bevy 版本之间会变化，编译器是检查手段。
不要发明 API 或未命名的第三方 crate 作为选定求解器。原因：Bevy 代码保持惯用 ECS，只使用有文档的 Bevy API。

参考

bevy-master 上的库固定保持 0.20.0。永久链接保持无版本。

官方文档

Assets - 官方资产目录。未选择第三方 crate。
Examples - 最新分支上的示例树。
3D examples - 网格、材质和光照示例。
ECS - Component、systems、Query、Startup、Update 和 .chain()。
Plugins - Plugin、DefaultPlugins、MinimalPlugins 和 add_plugins。

技能介绍

用途