SuperAPI AI 工具集

bevy-3d-materials

编程与开发

查看项目

更新于 10-16 10:38

技能介绍

用途

该技能用于在 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 路由器)。