bevy_gltf_blueprints (已弃用，推荐使用Blenvy)

bevy_gltf_blueprints 已弃用，推荐使用其继任者 Blenvy，它是 Blenvy项目 的一部分。Bevy bevy_gltf_blueprints 将不再进行开发或维护。有关背景信息，请参阅 #194。

基于 bevy_gltf_components 构建，这个crate在gltf文件内为 Bevy 定义Blueprint/Prefab，并允许在Bevy中生成它们。

• 允许您创建轻量级关卡，其中所有资产都是不同的gltf文件，在主关卡加载后加载
• 允许您在运行时以整洁的方式从gtlf文件生成不同的实体，包括简化的动画支持 !

Blueprint是一组可覆盖的组件 + 一个层次结构：即

* just a Gltf file with Gltf_extras specifying components 
* a component called BlueprintName

特别适用于使用 Blender 作为 Bevy 游戏引擎的编辑器，结合Blender插件，这些插件为您做了大量工作

• gltf_auto_export
• bevy_components

用法

以下是一个最小化使用示例

# Cargo.toml
[dependencies]
bevy="0.14"
bevy_gltf_blueprints = { version = "0.11.0"} 

use bevy::prelude::*;
use bevy_gltf_blueprints::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(BlueprintsPlugin)

        .run();
}

// not shown here: any other setup that is not specific to blueprints

fn spawn_blueprint(
    mut commands: Commands,
    keycode: Res<Input<KeyCode>>,
){
    if keycode.just_pressed(KeyCode::S) {
        let new_entity = commands.spawn((
            BlueprintName("Health_Pickup".to_string()), // mandatory !!
            SpawnHere, // mandatory !!
            TransformBundle::from_transform(Transform::from_xyz(x, 2.0, y)), // VERY important !!
            // any other component you want to insert
        ));
    }
}

安装

将以下内容添加到您的 [dependencies] 部分中 Cargo.toml

bevy_gltf_blueprints = "0.11.0"

或者使用 cargo add

cargo add bevy_gltf_blueprints

设置

use bevy::prelude::*;
use bevy_gltf_blueprints::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugin(BlueprintsPlugin)

        .run();
}

您可能想要配置您的“库”/“蓝图”设置

use bevy::prelude::*;
use bevy_gltf_blueprints::*;

fn main() {
    App::new()
        .add_plugins((
             BlueprintsPlugin{
                library_folder: "advanced/models/library".into() // replace this with your blueprints library path , relative to the assets folder,
                format: GltfFormat::GLB,// optional, use either  format: GltfFormat::GLB, or  format: GltfFormat::GLTF, or  ..Default::default() if you want to keep the default .glb extension, this sets what extensions/ gltf files will be looked for by the library
                aabbs: true, // defaults to false, enable this to automatically calculate aabb for the scene/blueprint
                material_library: true,  // defaults to false, enable this to enable automatic injection of materials from material library files
                material_library_folder: "materials".into() //defaults to "materials" the folder to look for for the material files
                ..Default::default()
            }
        ))
        .run();
}

从蓝图生成实体

您可以这样从蓝图生成实体

commands.spawn((
    BlueprintName("Health_Pickup".to_string()), // mandatory !!
    SpawnHere, // mandatory !!
    
    TransformBundle::from_transform(Transform::from_xyz(x, 2.0, y)), // optional
    // any other component you want to insert
))

一旦实际实体的生成完成，生成的蓝图将与蓝图的内容 合并！

重要：在生成蓝图本身时，您可以 添加 或 覆盖 蓝图内存在的组件：例如

添加蓝图内未指定的组件

在生成时，您可以添加任何需要的附加组件

commands.spawn((
    BlueprintName("Health_Pickup".to_string()),
    SpawnHere,
    TransformBundle::from_transform(Transform::from_xyz(x, 2.0, y)),
    // from Rapier/bevy_xpbd: this means the entity will also have a velocity component when inserted into the world
    Velocity {
        linvel: Vec3::new(vel_x, vel_y, vel_z),
        angvel: Vec3::new(0.0, 0.0, 0.0),
      },
))

覆盖蓝图内部指定的组件

当在蓝图生成时指定的任何组件也在蓝图内部指定，则该组件将覆盖最终生成的实体中的该组件

例如

commands.spawn((
    BlueprintName("Health_Pickup".to_string()),
    SpawnHere,
    TransformBundle::from_transform(Transform::from_xyz(x, 2.0, y)),
    HealthPowerUp(20)// if this is component is also present inside the "Health_Pickup" blueprint, that one will be replaced with this component during spawning
))

蓝图包

为了方便，也存在一个名为 BluePrintBundle 的蓝图包，它仅仅包含

• 一个 BlueprintName 组件
• 一个 SpawnHere 组件

附加信息

• 当生成蓝图时，所有其子实体（及其嵌套子实体等）也会获得一个 InBlueprint 组件，并被插入
• 在那种不希望出现的情况中，你可以在生成的蓝图实体上添加一个 NoInBlueprint 组件，上述组件将不会被添加
• 如果你想覆盖此crate查找蓝图（gltf文件）的路径，你可以添加一个 Library 组件，它将使用默认路径以外的路径

commands
    .spawn((
        Name::from("test"),
        BluePrintBundle {
            blueprint: BlueprintName("TestBlueprint".to_string()),
            ..Default::default()
        },
        Library("models".into()) // now the path to the blueprint above will be /assets/models/TestBlueprint.glb
    ))

• 此crate还提供了一个特殊可选的 GameWorldTag 组件：当你想在根实体内部保留所有生成的实体时，这非常有用

你可以在查询中使用它，将你的实体作为此“世界”的子实体添加。这样，所有你的关卡、动态实体等都被单独保留，与UI节点和其他与游戏世界无关的实体分开

注意：你应该只有一个实体被标记为该组件！

    commands.spawn((
        SceneBundle {
            scene: models
                .get(game_assets.world.id())
                .expect("main level should have been loaded")
                .scenes[0]
                .clone(),
            ..default()
        },
        bevy::prelude::Name::from("world"),
        GameWorldTag, // here it is
    ));

系统集

系统的顺序非常重要！

例如，为了在基于蓝图生成之后替换你的代理组件（当不能或不希望在使用真实组件的gltf文件中使用时充当替身的组件），应该发生在 之后

因此，bevy_gltf_blueprints 提供了一个 SystemSet 用于此目的：GltfBlueprintsSet

通常，系统的顺序应该是

bevy_gltf_components (GltfComponentsSet::Injection) → bevy_gltf_blueprints (GltfBlueprintsSet::Spawn, GltfBlueprintsSet::AfterSpawn) → replace_proxies

请参见 此处 了解如何正确设置

动画

bevy_gltf_blueprints 提供了一些轻量级的辅助函数来处理存储在gltf文件中的动画

• 一个 Animations 组件被插入到生成的（根）实体中，其中包含该实体/gltf文件内部包含的所有动画的哈希表。（这是Bevy的gltf结构中 named_animations 的副本）
• 一个 AnimationPlayerLink 组件被插入到生成的（根）实体中，使得触发/控制动画比在Bevy + Gltf文件中更容易

动画的工作流程如下

• 创建一个包含动画的gltf文件（使用Blender等），就像你通常所做的那样
• 在Bevy中，使用 bevy_gltf_blueprints 的样板（见上方章节），无需进行其他特定的设置
• 要控制实体的动画，你需要查询具有 AnimationPlayerLink 和 Animations 组件（由 bevy_gltf_blueprints 添加）的实体，并且这些实体还具有 AnimationPlayer 组件

例如

// example of changing animation of entities based on proximity to the player, for "fox" entities (Tag component)
pub fn animation_change_on_proximity_foxes(
    players: Query<&GlobalTransform, With<Player>>,
    animated_foxes: Query<(&GlobalTransform, &AnimationPlayerLink, &Animations ), With<Fox>>,

    mut animation_players: Query<&mut AnimationPlayer>,

){
    for player_transforms in players.iter() {
        for (fox_tranforms, link, animations) in animated_foxes.iter() {
            let distance = player_transforms
                .translation()
                .distance(fox_tranforms.translation());
            let mut anim_name = "Walk"; 
            if distance < 8.5 {
                anim_name = "Run"; 
            }
            else if distance >= 8.5 && distance < 10.0{
                anim_name = "Walk";
            }
            else if distance >= 10.0 && distance < 15.0{
                anim_name = "Survey";
            }
            // now play the animation based on the chosen animation name
            let mut animation_player = animation_players.get_mut(link.0).unwrap();
            animation_player.play_with_transition(
                animations.named_animations.get(anim_name).expect("animation name should be in the list").clone(), 
                Duration::from_secs(3)
            ).repeat();
        }
    }
}

请参见 此处 了解如何正确设置

特别是从 此处

材质

你有选项使用“材质库”在蓝图之间共享常见的纹理/材质，以避免资产和内存膨胀

例如，如果没有这个选项，使用相同材质和大型纹理的56个不同的蓝图会导致材质/纹理被嵌入56次！

您可以通过设置来配置此选项

material_library: true  // defaults to false, enable this to enable automatic injection of materials from material library files
material_library_folder: "materials".into() //defaults to "materials" the folder to look for for the material files

重要！您必须提前预加载材质库gltf文件，例如使用bevy_asset_loader，因为bevy_gltf_blueprints目前不处理运行时的加载。

请参阅以下示例，了解如何正确设置：这里

使用最新版本的Blender插件，可以自动化生成优化的蓝图和材质库。

旧模式

从版本0.7开始，新增了一个用于向后兼容的参数legacy_mode。

要禁用旧模式：（默认启用）

BlueprintsPlugin{legacy_mode: false}

如果您想使用bevy_components Blender插件和bevy_registry_export，您必须禁用旧模式！因为它创建的属性是以真实的ron文件格式编写的，而不是旧模式中的简化版本。

注意：未来版本将不支持旧模式，默认行为将是无旧模式。

示例

• 基本

• xbpd

• 动画

• 材质

• 多级多个blend文件

兼容的Bevy版本

主分支与最新的Bevy版本兼容，而bevy_main分支尝试跟踪Bevy的main分支（欢迎提交更新跟踪提交的PR）。

bevy_gltf_blueprints版本兼容性

许可证

本软件包及其所有代码、内容和资产均采用双重许可证，可任选其一：

• Apache许可证2.0版本（LICENSE-APACHE 或 https://apache.ac.cn/licenses/LICENSE-2.0）
• MIT许可证（LICENSE-MIT 或 https://opensource.org/licenses/MIT）