1个不稳定版本

新 0.1.0-alpha.1	2024年8月14日

#258 在游戏开发

112 每月下载量

MIT/Apache

155KB
3K SLoC

blenvy

此crate允许您

直接在gltf文件中定义Bevy组件并在Bevy侧实例化。
在gltf文件中定义Bevy的蓝图/预制件并在Bevy中实例化。
- 允许您创建轻量级关卡，其中所有资产都是不同的gltf文件，并在主关卡加载后加载。
- 允许您以干净的方式在运行时从gltf文件中实例化不同的实体，包括简化的动画支持！
蓝图是一组可重写的组件+一个层次结构：即
```
  * just a Gltf file with Gltf_extras specifying components 
  * a component called BlueprintInfo
```
特别适用于使用Blender作为Bevy游戏引擎的编辑器，结合Blender插件，该插件为您做了很多工作
- blenvy
允许您将所有组件/注册类型导出为Json。其主要用例是作为blenvy Blender插件的骨干，该插件允许您在Blender中直接添加和编辑组件，使用Bevy的实际类型定义（以及您在Bevy中注册的任何自定义类型和组件）。
添加了轻松保存和加载Bevy游戏世界的功能。

利用蓝图和动态实体之间的分离
- 动态实体：在应用程序/游戏的生命周期中可以改变的实体
- 静态实体：不改变的实体（通常，您的关卡/环境的一部分）
并允许
- 一个简单的保存/加载工作流程，归功于上述
- 指定要保存或排除的实体
- 指定要保存或排除的组件
- 指定要保存或排除的资源
- 较小的保存文件（只保存实体的一部分）

特别适用于使用Blender作为Bevy游戏引擎的编辑器时，结合Blender插件，该插件为您做了大量工作（包括拆分，为您的静态和动态资产生成单独的gltf文件）。

使用方法

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

# Cargo.toml
[dependencies]
bevy="0.14"
blenvy = { version = "0.1.0-alpha.1"}

use bevy::prelude::*;
use blenvy::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(BlenvyPlugin::default())

        .add_systems(Startup, setup_game)
        .add_systems(Update, spawn_blueprint_instance)
        .run();
}


// this is how you setup & spawn a level from a blueprint
fn setup_game(
    mut commands: Commands,
) {

    // here we spawn our game world/level, which is also a blueprint !
    commands.spawn((
        BlueprintInfo::from_path("levels/World.glb"), // all we need is a Blueprint info...
        SpawnBlueprint, // and spawnblueprint to tell blenvy to spawn the blueprint now
        HideUntilReady, // only reveal the level once it is ready
        GameWorldTag,
    ));
}

fn spawn_blueprint_instance(
    mut commands: Commands,
    keycode: Res<ButtonInput<KeyCode>>,
){
    if keycode.just_pressed(KeyCode::KeyS) {
        let new_entity = commands.spawn((
            BlueprintInfo::from_path("spawnable.glb"), // mandatory !!
            SpawnBlueprint, // mandatory !!
            TransformBundle::from_transform(Transform::from_xyz(0.0, 2.0, 0.2)), // VERY important !!
            // any other component you want to insert
        ));
    }
}

安装

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

blenvy = "0.1.0-alpha.1"

或使用cargo add

cargo add blenvy

设置

use bevy::prelude::*;
use blenvy::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugin(BlenvyPlugin::default())
        .run();
}

您可能需要配置您的设置

use bevy::prelude::*;
use blenvy::*;

fn main() {
    App::new()
        .add_plugins((
             BlenvyPlugin{
                aabbs: true, // defaults to false, enable this to automatically calculate aabb for the scene/blueprint
                ..Default::default()
            }
        ))
        .run();
}

从蓝图生成实体

您可以通过以下方式从蓝图生成实体

commands.spawn((
    BlueprintInfo::from_path("Health_Pickup.glb"), // mandatory !!
    // or the alterive: BlueprintInfo{name:"health pickup1".into(), path:"Health_Pickup.glb".into()}
    SpawnBlueprint, // mandatory !!
    
    TransformBundle::from_transform(Transform::from_xyz(x, 2.0, y)), // optional
    // any other component you want to insert
))

一旦实际实体的生成完成，蓝图的内容（组件、子实体等）将与实体本身的内容合并。

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

添加蓝图内部未指定的组件

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

commands.spawn((
    BlueprintInfo::from_path("Health_Pickup.glb"),
    SpawnBlueprint,
    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((
    BlueprintInfo::from_path("Health_Pickup.glb"),
    SpawnBlueprint,
    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，它只是包含

一个BlueprintInfo组件
一个SpawnBlueprint组件

附加信息

当生成蓝图时，一个FromBlueprint组件将被插入到其所有子实体（以及嵌套子实体等）中
此crate还提供了一个特殊的可选GameWorldTag组件：当您想要将所有生成的实体保持在根实体内部时，这非常有用

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

注意：您应该只有一个实体带有该组件！

   commands.spawn((
        BlueprintInfo::from_path("levels/World.glb"), 
        SpawnBlueprint,
        HideUntilReady,
        GameWorldTag, // here it is
    ));

注册表

Blenvy会自动导出一个包含所有注册组件/类型的Json文件，以便在Blenvy Blender插件中创建允许您直接在Blender中添加和编辑组件的UI。

输出文件将在每次运行您的应用时，在Startup计划中生成。
每次您编译和运行应用时，输出Json文件都将更新。

材质

如果您在Blender侧启用它，Blenvy将使用“材质库”在蓝图之间共享常见的纹理/材质，以避免资产和内存膨胀：例如，如果没有此选项，56个不同的蓝图使用相同的大纹理的材质会导致该材质/纹理被嵌入56次！

使用Blender插件自动生成优化蓝图和材质库。

动画

blenvy提供了一些轻量级的助手来处理存储在gltf文件中的动画

它支持蓝图级别的动画（由同一蓝图的所有蓝图实例共享）

一个BlueprintAnimations组件，该组件被插入到生成的（根）实体中，其中包含该实体/gltf文件中包含的所有动画的哈希表。
一个被插入到生成的（根）实体中的 BlueprintAnimationPlayerLink 组件，以便更容易找到 Bevy 的 AnimationPlayer 和 AnimationTransitions 组件。

以及实例级别的动画（特定于一个实例）。

一个 InstanceAnimations 组件，该组件被插入到生成的（根）实体中，其中包含所有 特定于该实例 的动画的哈希表。
一个 InstanceAnimationPlayerLink 组件被插入到生成的（根）实体中，以便更容易找到上述动画的 Bevy 的 AnimationPlayer 和 AnimationTransitions 组件。

动画的工作流程如下：

创建一个包含动画的 gltf 文件（使用 Blender 等），就像你通常做的那样。
在 Bevy 中，使用 blenvy 模板（见上面的章节），不需要进一步的特定设置。
要控制实体的动画，你需要查询具有 BlueprintAnimationPlayerLink 和 BlueprintAnimations 组件（由 blenvy 添加）以及具有 AnimationPlayer 组件的实体。

例如（蓝图动画）

pub fn trigger_blueprint_animations(
    animated_foxes: Query<(&BlueprintAnimationPlayerLink, &BlueprintAnimations), With<Fox>>,
    mut animation_players: Query<(&mut AnimationPlayer, &mut AnimationTransitions)>,
    keycode: Res<ButtonInput<KeyCode>>,
){
    if keycode.just_pressed(KeyCode::KeyW) {
        for (link, animations) in animated_foxes.iter() {
            let (mut animation_player, mut animation_transitions) =
            animation_players.get_mut(link.0).unwrap();

            let anim_name = "Walk";
            animation_transitions
                .play(
                    &mut animation_player,
                    animations
                        .named_indices
                        .get(anim_name)
                        .expect("animation name should be in the list")
                        .clone(),
                    Duration::from_secs(5),
                )
                .repeat();
        }
    }
}

有关如何正确设置的信息，请参阅 https://github.com/kaosat-dev/Blenvy/tree/main/examples/blenvy/animation

附加功能

此crate还包括对 gltf 文件中灯光的自动处理，以尽可能匹配 Blender 的 eevee 渲染。

BlenderLightShadows（由 gltf_auto_export Blender 插件自动生成）允许你在 Blender 中切换灯光的阴影开/关，并在 Bevy 中具有匹配的行为。
BlenderBackgroundShader（也称为背景颜色）也在 Bevy 侧自动设置。
BlenderShadowSettings 将 bevy 侧的 cascade_size 设置为与 Blender 中配置的匹配。