迁移指南：0.13 到 0.14

动画 #

AnimationClip 现在使用 UUID，NoOpTypeIdHash 现在称为 NoOpHash #

• PR #11707
• 动画

AnimationClip 现在使用 UUID 而不是基于 Name 组件的层次路径来引用骨骼。这有几个后果

• 一个新的组件 AnimationTarget 应该放置在你希望动画的每个骨骼上，以指定它的 UUID 和关联的 AnimationPlayer。glTF 加载器会根据需要自动创建这些组件，因此 glTF 模型的大多数用法都不需要更改。
• 在树中移动骨骼或重命名骨骼不再阻止 AnimationPlayer 影响它。
• 动态更改 AnimationPlayer 组件可能需要手动更新 AnimationTarget 组件。

具有 AnimationPlayer 组件的实体现在可能拥有也具有 AnimationPlayer 组件的后代。但是，它们可能不会动画相同的骨骼。

此外，NoOpTypeIdHash 和 NoOpTypeIdHasher 已重命名为 NoOpHash 和 NoOpHasher。

实现 AnimationGraph 以混合动画 #

• PR #11989
• 动画

AnimationPlayer 现在不能再单独播放动画：它们需要与 Handle<AnimationGraph> 配对。使用 AnimationPlayer 播放动画的代码需要先创建一个 AnimationGraph 资产，添加你想要播放的片段的节点（或片段），然后将该节点的索引提供给 AnimationPlayer 的 play 方法。

// 0.13
fn setup(mut commands: Commands, mut animations: ResMut<Assets<AnimationClip>>) {
    let mut animation = AnimationClip::default();

    // ...

    let mut player = AnimationPlayer::default();
    player.play(animations.add(animation));

    commands.spawn((
        player,
        // ...
    ));
}

// 0.14
fn setup(
    mut commands: Commands,
    mut animations: ResMut<Assets<AnimationClip>>,
    // You now need access to the `AnimationGraph` asset.
    mut graphs: ResMut<Assets<AnimationGraph>>,
) {
    let mut animation = AnimationClip::default();

    // ...

    // Create a new `AnimationGraph` and add the animation handle to it.
    let (graph, animation_index) = AnimationGraph::from_clip(animations.add(animation));

    let mut player = AnimationPlayer::default();
    // Play the animation index, not the handle.
    player.play(animation_index);

    commands.spawn((
        player,
        // Add the new `AnimationGraph` to the assets, and spawn the entity with its handle.
        graphs.add(graph),
        // ...
    ));
}

此外，AnimationPlayer::play_with_transition() 方法已被删除，并被 AnimationTransitions 组件替换。如果你之前使用的是 AnimationPlayer::play_with_transition()，请将你要播放的所有动画添加到 AnimationGraph 并创建一个 AnimationTransitions 组件来管理它们之间的混合。

有关此更改的更多信息，你可能感兴趣的是 RFC 51.

将颜色乘以 f32 将不再忽略 alpha 通道 #

• PR #12575
• 动画
• 颜色
• 数学
• 渲染

之前可以通过 f32 将 Color 乘以或除以，现在已删除。现在必须操作特定的颜色空间，例如 LinearRgba。此外，这些操作过去会跳过 alpha 通道，但现在不会了。

// 0.13
let color = Color::RgbaLinear {
    red: 1.0,
    green: 1.0,
    blue: 1.0,
    alpha: 1.0,
} * 0.5;

// Alpha is preserved, ignoring the multiplier.
assert_eq!(color.a(), 1.0);

// 0.14
let color = LinearRgba {
    red: 1.0,
    green: 1.0,
    blue: 1.0,
    alpha: 1.0,
} * 0.5;

// Alpha is included in multiplication.
assert_eq!(color.alpha, 0.5);

如果你需要 alpha 通道保持不变，请考虑创建自己的辅助方法

fn legacy_div_f32(color: &mut LinearRgba, scale: f32) {
    color.red /= scale;
    color.green /= scale;
    color.blue /= scale;
}

let mut color = LinearRgba {
    red: 1.0,
    green: 1.0,
    blue: 1.0,
    alpha: 1.0,
};

legacy_div_f32(&mut color, 2.0);

如果你不介意 alpha 发生变化，但需要它保持在 0.0 到 1.0 的范围内，请考虑将其钳位

let mut color = LinearRgba {
    red: 1.0,
    green: 1.0,
    blue: 1.0,
    alpha: 1.0,
} * 10.0;

// Force alpha to be within [0.0, 1.0].
color.alpha = color.alpha.clamp(0.0, 1.0);

请注意，在某些情况下，例如渲染精灵，alpha 会自动钳位，因此你不需要手动执行。

应用程序 #

OnEnter 状态调度程序现在在 Startup 调度程序之前运行 #

• PR #11426
• 应用程序
• ECS

在 Bevy 0.13 中，通过 [app.init_state] 初始化的状态的 [OnEnter] 调度程序将在 Startup 调度程序中的任何系统之后运行。这是因为 [apply_state_transitions] 仅在 [StateTransition] 调度程序期间运行。

这是一个微妙的错误：游戏可能处于特定状态，而没有首先进入该状态。现在，[OnEnter] 状态转换逻辑会立即处理。有关此决定的更多上下文，请参阅 bevy#13968。

要进行迁移，请选择以下选项之一

1. 将你的启动系统移到一个状态，作为你等待的状态的一个变体（例如 AppState::Setup），然后在设置完成后从该状态过渡出来。
2. 将你的启动系统移到一个状态，并将另一个状态设置为一个 子状态，该子状态依赖于启动状态的完成（例如 SetupState::SetupComplete）。

// 0.13
#[derive(States, Default)]
enum AppState {
    #[default]
    InMenu,
    InGame,
}

app
   .init_state::<AppState>()
   .add_systems(Startup, initial_setup)
   .add_systems(OnEnter(AppState::InMenu), relies_on_initial_setup);

// 0.14 (Solution 1)
#[derive(States, Default)]
enum AppState {
    // Make this the default instead of `InMenu`.
    #[default]
    Setup
    InMenu,
    InGame,
}

fn transition_to_in_menu(mut app_state: ResMut<NextState<AppState>>) {
    app_state.set(AppState::InMenu);
}

app
    .init_state::<AppState>()
    .add_systems(OnEnter(AppState::Setup), initial_setup)
    .add_system(Update, transition_to_in_menu.run_if(in_state(AppState::Setup)))
    .add_systems(OnEnter(AppState::InMenu), relies_on_initial_setup);

// 0.14 (Solution 2)
#[derive(States, Default)]
enum SetupState {
    #[default]
    SettingUp,
    SetupComplete,
}

#[derive(SubStates, Default)]
#[source(SetupState = SetupState::SetupComplete)]
enum AppState {
    #[default]
    InMenu,
    InGame,
}

fn finish_setup(mut app_state: ResMut<NextState<SetupState>>) {
    app_state.set(SetupState::SetupComplete);
}

app
    .init_state::<SetupState>()
    // Note that we don't call `init_state()` for substates!
    .add_sub_state::<AppState>()
    .add_systems(OnEnter(AppState::InitialSetup), initial_setup)
    .add_system(Update, finish_setup.run_if(in_state(AppState::Setup)))
    .add_systems(OnEnter(AppState::InMenu), relies_on_initial_setup);

将 SubApp 与 App 分开 #

• PR #9202
• 应用程序

SubApp 已从 App 中分离出来，因此与这些类型交互时涉及一些较大的更改。

构造 SubApp #

SubApp 不再包含 App，因此您不再能够将 App 转换为 SubApp。此外，提取函数现在必须在构造函数之外设置。

// 0.13
#[derive(AppLabel, Clone, Copy, Hash, PartialEq, Eq, Debug)]
struct MySubApp;

let mut app = App::new();
let mut sub_app = App::empty();

sub_app.add_systems(Main, ...);
sub_app.insert_resource(...);

app.insert_sub_app(MySubApp, SubApp::new(sub_app, |main_world, sub_app| {
    // Extraction function.
}));

// 0.14
#[derive(AppLabel, Clone, Copy, Hash, PartialEq, Eq, Debug)]
struct MySubApp;

let mut app = App::new();
// Use `SubApp::new()` instead of `App::new()`.
let mut sub_app = SubApp::new();

// Instead of setting the extraction function when you create the `SubApp`, you must set it
// afterwards. If you do not set an extraction function, it will do nothing.
sub_app.set_extract(|main_world, sub_world| {
    // Extraction function.
});

// You can still add systems and resources like normal.
sub_app.add_systems(Main, ...);
sub_app.insert_resource(...);

app.insert_sub_app(MySubApp, sub_app);

App 的变化 #

App 不再是 Send，但 SubApp 仍然是。

由于 App 和 SubApp 的分离，一些其他方法也发生了变化。

首先，App::world 作为属性不再可以直接访问。请改用 App::world 和 App::world_mut 获取器。

#[derive(Component)]
struct MyComponent;

// 0.13
let mut app = App::new();
println!("{:?}", app.world.id());
app.world.spawn(MyComponent);

// 0.14
let mut app = App::new();
println!("{:?}", app.world().id()); // Notice the added paranthesese.
app.world_mut().spawn(MyComponent);

其次，子应用程序的所有获取器现在返回 SubApp 而不是 App。这包括 App::sub_app、App::sub_app_mut、App::get_sub_app 和 App::get_sub_app_mut。

#[derive(AppLabel, Clone, Copy, Hash, PartialEq, Eq, Debug)]
struct MySubApp;

let mut app = App::new();
app.insert_sub_app(MySubApp, SubApp::new());

assert_eq!(app.sub_app(MySubApp).type_id(), TypeId::of::<SubApp>());

最后，App::runner 和 App::main_schedule_label 现在是私有的。您不再能够获取运行器闭包，但您可以使用 SubApp::update_schedule 获取主调度标签。

let app = App::new();
let label = app.main().update_schedule;

App 上的第三方特性 #

如果您在 App 上实现了扩展特性，请考虑也将其在 SubApp 上实现。

trait SpawnBundle {
    /// Spawns a new `Bundle` into the `World`.
    fn spawn_bundle<T: Bundle>(&mut self, bundle: T) -> &mut Self;
}

impl SpawnBundle for App {
    fn spawn_bundle<T: Bundle>(&mut self, bundle: T) -> &mut Self {
        self.world_mut().spawn(bundle);
        self
    }
}

/// `SubApp` has a very similar API to `App`, so the code will usually look the same.
impl SpawnBundle for SubApp {
    fn spawn_bundle<T: Bundle>(&mut self, bundle: T) -> &mut Self {
        self.world_mut().spawn(bundle);
        self
    }
}

使 AppExit 更具体地说明退出原因 #

• PR #13022
• 应用程序

AppExit 事件现在是一个枚举类型，表示代码是否成功退出。如果您要构造它，您现在必须指定 Success 或 Error。

// 0.13
fn send_exit(mut writer: EventWriter<AppExit>) {
    writer.send(AppExit);
}

// 0.14
fn send_exit(mut writer: EventWriter<AppExit>) {
    writer.send(AppExit::Success);
    // Or...
    writer.send(AppExit::Error(NonZeroU8::new(1).unwrap()));
}

如果您在系统中订阅了此事件，请考虑使用 match 来判断它是成功还是错误。

// 0.13
fn handle_exit(mut reader: EventReader<AppExit>) {
    for app_exit in reader.read() {
        // Something interesting here...
    }
}

// 0.14
fn handle_exit(mut reader: EventReader<AppExit>) {
    for app_exit in reader.read() {
        match *app_exit {
            AppExit::Success => {
                // Something interesting here...
            },
            AppExit::Error(exit_code) => panic!("App exiting with an error! (Code: {exit_code})"),
        }
    }
}

此外，App::run() 现在返回 AppExit 而不是单位类型 ()。由于 AppExit 实现了 Termination，您现在可以从主函数中返回它。

// 0.13
fn main() {
    App::new().run()
}

// 0.14
fn main() -> AppExit {
    App::new().run()
}

// 0.14 (alternative)
fn main() {
    // If you want to ignore `AppExit`, you can add a semicolon instead. :)
    App::new().run();
}

最后，如果您配置了自定义 App 运行器函数，它现在必须返回 AppExit。

let mut app = App::new();

app.set_runner(|_app| {
    // ...

    // Return success by default, though you may also return an error code.
    AppExit::Success
});

弃用动态插件 #

• PR #13080
• 应用程序

动态插件现在已弃用。如果可能，请从您的代码中删除所有使用它们的地方。

// 0.13
// This would be compiled into a separate dynamic library.
#[derive(DynamicPlugin)]
pub struct MyPlugin;

impl Plugin for MyPlugin {
    // ...
}

// This would be compiled into the main binary.
App::new()
    .load_plugin("path/to/plugin")
    .run()

// 0.14
// This would now be compiled into the main binary as well.
pub struct MyPlugin;

impl Plugin for MyPlugin {
    // ...
}

App::new()
    .add_plugins(MyPlugin)
    .run()

如果您无法做到这一点，您可以通过使用 #[allow(deprecated)] 注解所有使用来暂时静默弃用警告。请注意，当前的动态插件系统将在下一个主要 Bevy 版本中删除，因此您最终将不得不迁移。您可能对这些更安全、相关的链接感兴趣

• Bevy Assets - 脚本: Bevy 的脚本和修改库
• Bevy Assets - 开发工具: 热重载和其他开发功能
• stabby: 稳定的 Rust ABI

如果您确实无法没有动态插件，您可以从 Bevy 复制代码并将其添加到您的项目中。

将状态初始化方法移至 bevy::state #

• PR #13637
• 应用程序
• ECS

State 已移至 bevy::state。随之而来的是，App::init_state 已从普通方法移至扩展特性。如果您没有使用前置声明，现在可能需要导入 AppExtStates 才能使用此方法。（此特性位于 bevy_state 特性标志后面，您可能需要启用它。）

// 0.13
App::new()
    .init_state::<MyState>()
    .run()

// 0.14
use bevy::state::app::AppExtStates as _;

App::new()
    .init_state::<MyState>()
    .run()

资产 #

删除 UpdateAssets 和 AssetEvents 调度程序 #

• PR #11986
• 资产

UpdateAssets 调度程序已被删除。如果您将系统添加到此调度程序中，请将其移至 PreUpdate 上运行。（您可能需要使用 system.before(...) 和 system.after(...) 来配置排序。）

// 0.13
App::new()
    .add_plugins(DefaultPlugins)
    .add_systems(UpdateAssets, my_system)
    .run()

// 0.14
App::new()
    .add_plugins(DefaultPlugins)
    .add_systems(PreUpdate, my_system)
    .run()

此外，AssetEvents 已从 ScheduleLabel 更改为 First 调度程序中的 SystemSet。

// 0.13
App::new()
    .add_plugins(DefaultPlugins)
    .add_systems(AssetEvents, my_system)
    .run()

// 0.14
App::new()
    .add_plugins(DefaultPlugins)
    .add_systems(First, my_system.in_set(AssetEvents))
    .run()

在特性中使用 async fn 而不是 BoxedFuture #

• PR #12550
• 资产

在 Rust 1.75 中，async fn 已为特性稳定。一些特性已从返回 BoxedFuture 切换为 async fn，具体来说是

• AssetReader
• AssetWriter
• AssetLoader
• AssetSaver
• Process

请更新您的特性实现。

// 0.13
impl AssetLoader for MyAssetLoader {
    // ...

    fn load<'a>(
        &'a self,
        reader: &'a mut Reader,
        _settings: &'a (),
        _load_context: &'a mut LoadContext,
    ) -> BoxedFuture<'a, Result<Self::Asset, Self::Error>> {
        // Note that you had to pin the future.
        Box::pin(async move {
            let mut bytes = Vec::new();
            reader.read_to_end(&mut bytes).await?;
            Ok(bytes)
        })
    }
}

// 0.14
impl AssetLoader for MyAssetLoader {
    // ...

    async fn load<'a>(
        &'a self,
        reader: &'a mut Reader<'_>,
        _settings: &'a (),
        _load_context: &'a mut LoadContext<'_>,
    ) -> Result<Self::Asset, Self::Error> {
        // No more need to pin the future, just write it!
        let mut bytes = Vec::new();
        reader.read_to_end(&mut bytes).await?;
        Ok(bytes)
    }
}

由于这些特性现在使用 async，因此它们不再是对象安全的。如果您需要接收或存储 &dyn Trait，请改用 &dyn ErasedTrait 变体。例如

// 0.13
struct MyReader(Box<dyn AssetReader>);

// 0.14
struct MyReader(Box<dyn ErasedAssetReader>);

在 ProcessResult 中添加 Ignore 变体 #

• PR #12605
• 资产

ProcessResult 枚举类型用于资产加载，它有一个新的 Ignore 变体。您可能需要更新您的 match 语句。

删除 Handle<T> 的 Into<AssetId<T>> #

• PR #12655
• 资产

使用 Into 从 Handle 转换为 AssetId 已被删除，因为它是一个易于出错的地方，可能会在 Handle 是强引用时删除资产。如果您需要 AssetId，请改用 Handle::id()。

// 0.13
let id: AssetId<T> = handle.into();

// 0.14
let id = handle.id();

在 Reader 中添加 AsyncSeek 特性以能够在资产加载器中进行查找 #

• PR #12547
• 资产

资产加载器的 Reader 类型别名现在需要新的 AsyncSeek 特性。请为必须是 Reader 的任何结构实现 AsyncSeek，或者在不支持查找的情况下使用其他方法。

如果您遇到了问题，请在 bevy#12880 上告诉我们，帮助我们在 0.15 版本中改进设计！

在 LoadState::Failed 中添加错误信息 #

• PR #12709
• 资产

Rust 以其错误处理而自豪，Bevy 一直在稳步赶上。以前，在使用 AssetServer::load_state（及其变体）检查资产是否已加载时，返回的错误信息只是空的 LoadState::Failed。这对调试来说没什么用！

现在，完整的 AssetLoadError 包含在 Failed 中，以便准确地告诉您出了什么问题。您可能需要更新您的 match 和 if let 语句以处理此新值。

// 0.13
match asset_server.load_state(asset_id) {
    // ...
    LoadState::Failed => eprintln!("Could not load asset!"),
}

// 0.14
match asset_server.load_state(asset_id) {
    // ...
    LoadState::Failed(error) => eprintln!("Could not load asset! Error: {}", error),
}

此外，LoadState 中的 Copy、PartialOrd 和 Ord 实现已被删除。您可以显式调用 .clone() 而不是复制枚举类型，您也可以手动重新实现 Ord 作为帮助器方法（如果需要）。

将 AssetMetaCheck 设为 AssetPlugin 的字段 #

• PR #13177
• 资产

AssetMetaCheck 用于配置 AssetPlugin 如何读取 .meta 文件。它以前是一个资源，但现在已更改为 AssetPlugin 中的字段。如果您使用 DefaultPlugins，您可以使用 .set 来配置此字段。

// 0.13
App::new()
    .add_plugins(DefaultPlugins)
    .insert_resource(AssetMetaCheck::Never)
    .run()

// 0.14
App::new()
    .add_plugins(DefaultPlugins.set(AssetPlugin {
        meta_check: AssetMetaCheck::Never,
        ..default()
    }))
    .run()

使 LoadContext 使用构建器模式 #

• PR #13465
• 资产

LoadContext 用于 AssetLoader，它已更新，因此其所有 load_* 方法都已合并到一个构建器结构体中。

// 0.13
load_context.load_direct(path);
// 0.14
load_context.loader().direct().untyped().load(path);

// 0.13
load_context.load_direct_with_reader(reader, path);
// 0.14
load_context.loader().direct().with_reader(reader).untyped().load(path);

// 0.13
load_context.load_untyped(path);
// 0.14
load_context.loader().untyped().load(path);

// 0.13
load_context.load_with_settings(path, settings);
// 0.14
load_context.loader().with_settings(settings).load(path);

使用 RenderAssetUsages 在加载过程中配置 gLTF 网格和材质 #

• PR #12302
• 资产
• 渲染

现在可以使用 GltfLoaderSettings 配置是否应在主世界、渲染世界或两者中加载网格和材质。load_meshes 字段已从 bool 更改为 RenderAssetUsages 位标志，并且添加了一个新的 load_materials 字段。

您可能需要更新所有 gLTF .meta 文件。

// 0.13
load_meshes: true

// 0.14
load_meshes: ("MAIN_WORLD | RENDER_WORLD")

如果您在加载 gLTF 文件时使用 AssetServer::load_with_settings，您还需要更新

// 0.13
asset_server.load_with_settings("model.gltf", |s: &mut GltfLoaderSettings| {
    s.load_meshes = true;
});

// 0.14
asset_server.load_with_settings("model.gltf", |s: &mut GltfLoaderSettings| {
    s.load_meshes = RenderAssetUsages::MAIN_WORLD | RenderAssetUsages::RENDER_WORLD;
});

将 RenderMaterials 及类似类型合并到 RenderAssets 中，为目标类型实现 RenderAsset #

• PR #12827
• 资产
• 渲染

RenderMaterials、RenderMaterials2d 和 RenderUiMaterials 已被 RenderAssets 资源替换。如果您需要使用 AssetId 访问 PreparedMaterial<T>，请改用 RenderAssets::get。

此外，RenderAsset 特性现在应该为目标类型而不是源类型实现。如果您需要访问源类型，请使用 RenderAsset::SourceAsset 关联类型。

// 0.13
impl RenderAsset for Image {
    type PreparedAsset = GpuImage;

    // ...
}

// 0.14
impl RenderAsset for GpuImage {
    type SourceAsset = Image;

    // ...
}

音频 #

在取消生成音频实体时修复对子项的剩余引用 #

• PR #12407
• 音频

您可以使用 PlaybackMode 枚举类型配置生成的音频的行为。它的一个变体 PlaybackMode::Despawn 会在音频播放完毕时取消生成实体。

以前有一个错误，导致它只会取消生成实体，而不会取消生成其子项。此错误已修复，现在在音频播放完毕时会调用 despawn_recursive()。

如果您依赖此行为，请考虑使用 PlaybackMode::Remove 只从实体中删除音频组件，或者使用 AudioSink::empty() 来检查是否有任何音频已播放完毕，并手动 despawn() 它。

颜色 #

彻底修改 Color #

• PR #12163
• 颜色
• Gizmos
• 渲染
• 文本
• UI

Bevy 的颜色支持已经过重大修改，并随之而来的是新的 bevy::color 模块。系好安全带，很多东西都变了！

颜色空间表示 #

Bevy 的主要 Color 枚举类型用于在许多不同的颜色空间（例如 RGB、HSL 等）中表示颜色。以前，这些颜色空间都作为变体内联表示。

enum Color {
    Rgba {
        red: f32,
        green: f32,
        blue: f32,
        alpha: f32,
    },
    Hsla {
        hue: f32,
        saturation: f32,
        lightness: f32,
        alpha: f32,
    },
    // ...
}

此方法已更改，现在每个颜色空间都有其自己的专用结构体。

struct Srgba {
    red: f32,
    green: f32,
    blue: f32,
    alpha: f32,
}

struct Hsla {
    hue: f32,
    saturation: f32,
    lightness: f32,
    alpha: f32,
}

enum Color {
    Srgba(Srgba),
    Hsla(Hsla),
    // ...
}

这样可以更轻松地组织和管理不同的颜色空间，并且还添加了许多新的颜色空间！为了处理此更改，您可能需要更新您的 match 语句。

// 0.13
match color {
    Color::Rgba { red, green, blue, alpha } => {
        // Something cool here!
    },
    _ => {},
}

// 0.14
match color {
    Color::Srgba(Srgba { red, green, blue, alpha }) => {
        // Something cool here!
    },
    // If you explicitly match every possible color space, you may need to handle more variants.
    // Color::Xyza(Xyza { x, y, z, alpha }) => {
    //     // Something else even cooler here!
    // },
    _ => {}
}

此外，您现在必须在颜色空间之间转换时使用 From 和 Into 实现，而不是像以前那样使用帮助器方法，例如 as_rgba 和 as_hsla。

// 0.13
let color = Color::rgb(1.0, 0.0, 1.0).as_hsla();

// 0.14
let color: Hsla = Srgba::rgb(1.0, 0.0, 1.0).into();

Color 方法 #

所有与 RGB 相关的都已重命名为 sRGB。这包括 Color::Rgba 变为 Color::Srgba，以及 Color::rgb 和 Color::rgb_u8 变为 Color::srgb 和 Color::srgb_u8。

由于会导致静默的、相对昂贵的转换，因此已删除了访问 Color 的特定通道的方法。这包括 Color::r、Color::set_r、Color::with_r，以及 g、b h、s 和 l 的所有等效方法。将您的 Color 转换为所需的颜色空间，在那里执行您的操作，然后转换回来。

// 0.13
let mut color = Color::rgb(0.0, 0.0, 0.0);
color.set_b(1.0);

// 0.14
let color = Color::srgb(0.0, 0.0, 0.0);
let srgba = Srgba {
    blue: 1.0,
    ..Srgba::from(color),
};
let color = Color::from(srgba);

Color::hex 已移至 Srgba::hex。调用 .into() 或手动构造 Color::Srgba 变体进行转换。

Color::rgb_linear 和 Color::rgba_linear 已重命名为 Color::linear_rgb 和 Color::linear_rgba 以符合 LinearRgba 结构体的命名方案。

Color::as_linear_rgba_f32 和 Color::as_linear_rgba_u32 已被删除。请改用 LinearRgba::to_f32_array 和 LinearRgba::to_u32，并在必要时进行转换。

已删除了将 LCH 或 HSL 颜色转换为浮点数数组或 Vec 类型的其他几个颜色转换方法。请在外部重新实现这些方法，或者如果发现它们特别有用，请打开一个 PR 重新添加它们。

Color 上的向量场算术运算（加、减、乘以 f32 和除以 f32）已被移除。请将您的颜色转换为 LinearRgba 空间并在那里显式执行运算。这在处理自发光或 HDR 颜色时尤其重要，它们的色彩通道值通常超出普通 0 到 1 范围。

Alpha #

Alpha，也称为透明度，过去用字母 a 来表示。现在在结构体和方法中用其全称来表示。

• Color::set_a、Color::with_a 和 Color::a 现在分别为 Color::set_alpha、Color::with_alpha 和 Color::alpha。这些是新 Alpha 特征的一部分。
• 此外，Color::is_fully_transparent 现在也属于 Alpha 特征。

CSS 常量 #

各种 CSS 颜色常量不再直接存储在 Color 中。而是定义在 Srgba 颜色空间中，并通过 bevy::color::palettes 访问。在它们上调用 .into() 将它们转换为 Color 以便快速调试使用。

// 0.13
let color = Color::BLUE;

// 0.14
use bevy::color::palettes::css::BLUE;

let color = BLUE;

请注意，palettes::css 不一定与之前定义的常量一一对应，因为一些名称和颜色已经更改以符合 CSS 规范。如果您需要与之前相同的颜色，请查看下面的表格或使用来自 旧常量 的颜色值。

切换到 LinearRgba #

WireframeMaterial、ExtractedUiNode、ExtractedDirectionalLight、ExtractedPointLight、ExtractedSpotLight 和 ExtractedSprite 现在存储 LinearRgba 而不是多态的 Color。此外，Color 不再实现 AsBindGroup。您应该存储 LinearRgba 以避免转换成本。

将 WGSL 数学常量和颜色运算从 bevy_pbr 移动到 bevy_render #

• PR #13209
• 颜色

用于着色器的数学常量和颜色转换函数已从 bevy_pbr::utils 移动到 bevy_render::maths 和 bevy_render::color_operations。如果您在自己的着色器中依赖这些，请更新您的导入语句。

// 0.13
#import bevy_pbr::utils::{PI, rgb_to_hsv}

// 0.14
#import bevy_render::{maths::PI, color_operations::rgb_to_hsv}

移除旧的颜色空间工具 #

• PR #12105
• 颜色
• 渲染

SrgbColorSpace 特征、HslRepresentation 结构体和 LchRepresentation 结构体已被移除，取而代之的是特定颜色空间结构体。

对于 SrgbColorSpace，请使用 Srgba::gamma_function() 和 Srgba::gamma_function_inverse()。如果您使用过 SrgbColorSpace 的 u8 实现，请先将其转换为 f32。

// 14 is random, this could be any number.
let nonlinear: u8 = 14;

// Apply gamma function, converting `u8` to `f32`.
let linear: f32 = Srgba::gamma_function(nonlinear as f32 / 255.0);

// Convert back to a `u8`.
let linear: u8 = (linear * 255.0) as u8;

请注意，这种转换可能很昂贵，尤其是在 Update 调度期间调用时。请考虑直接使用 f32。

HslRepresentation 和 LchRepresentation 可以用 Srgba、Hsla 和 Lcha 之间的 From 实现来代替。

// 0.13
let srgb = HslRepresentation::hsl_to_nonlinear_srgb(330.0, 0.7, 0.8);
let lch = LchRepresentation::nonlinear_srgb_to_lch([0.94, 0.66, 0.8]);

// 0.14
let srgba: Srgba = Hsla::new(330.0, 0.7, 0.8, 1.0).into();
let lcha: Lcha = Srgba::new(0.94, 0.66, 0.8, 1.0).into();

在 ColorAttachment 中使用 LinearRgba #

• PR #12116
• 颜色
• 渲染

ColorAttachment::new() 现在为 clear_color 接受 Option<LinearRgba> 而不是 Option<Color>。您可以使用 From<Color> 实现来转换您的颜色。

let clear_color: Option<LinearRgba> = Some(color.into());

开发工具 #

移除 close_on_esc #

• PR #12859
• 开发工具

close_on_esc 系统已被移除，因为它过于主观且缺乏定制性。如果您使用过此系统，您可以复制其内容如下。

pub fn close_on_esc(
    mut commands: Commands,
    focused_windows: Query<(Entity, &Window)>,
    input: Res<ButtonInput<KeyCode>>,
) {
    for (window, focus) in focused_windows.iter() {
        if !focus.focused {
            continue;
        }

        if input.just_pressed(KeyCode::Escape) {
            commands.entity(window).despawn();
        }
    }
}

您可能对使用操作系统提供的内置快捷键感兴趣，例如 Alt+F4 和 Command+Q。

诊断 #

使 sysinfo 诊断插件可选 #

• PR #12164
• 诊断

bevy::diagnostic 依赖于 sysinfo 来使用 SystemInformationDiagnosticsPlugin 跟踪 CPU 和内存使用情况，但是编译和轮询系统信息可能非常慢。sysinfo 现在位于 sysinfo_plugin 特征标志之后，该标志默认情况下在 bevy 中启用，但在 bevy_diagnostic 中则不启用。

如果您直接依赖于 bevy_diagnostic，请在 Cargo.toml 中切换标志。

[dependencies]
bevy_diagnostic = { version = "0.14", features = ["sysinfo_plugin"] }

如果您为 bevy 设置了 default-features = false，请在 Cargo.toml 中执行相同的操作。

[dependencies]
bevy = { version = "0.14", default-features = false, features = ["sysinfo_plugin"] }

改进 tracing 层定制 #

• PR #13159
• 诊断

Bevy 使用 tracing 通过 LogPlugin 处理日志记录和跨度。这可以使用 update_subscriber 字段进行定制，但它非常严格。这已经过修改，用更灵活的 custom_layer 替换了 update_subscriber 字段，它返回一个 Layer。

// 0.13
fn update_subscriber(_app: &mut App, subscriber: BoxedSubscriber) -> BoxedSubscriber {
    Box::new(subscriber.with(CustomLayer))
}

App::new()
    .add_plugins(LogPlugin {
        update_subscriber: Some(update_subscriber),
        ..default()
    })
    .run();

// 0.14
use bevy::log::tracing_subscriber;

fn custom_layer(_app: &mut App) -> Option<BoxedLayer> {
    // You can provide a single layer:
    return Some(CustomLayer.boxed());

    // Or you can provide multiple layers, since `Vec<Layer>` also implements `Layer`:
    Some(Box::new(vec![
        tracing_subscriber::fmt::layer()
            .with_file(true)
            .boxed(),
        CustomLayer.boxed(),
    ]))
}

App::new()
    .add_plugins(LogPlugin {
        custom_layer,
        ..default()
    })
    .run();

BoxedSubscriber 类型别名也被移除，它被 BoxedLayer 类型别名替换。

ECS #

使用观察者泛化 ECS 反应性 #

• PR #10839
• ECS

在 0.14 中，引入了 ECS 观察者：立即响应世界中事件的机制。作为此更改的一部分，Event 特征被扩展以要求 Component。#[derive(Event)] 现在自动为带注释的类型实现 Component，这可能会破坏也 #[derive(Component)] 的类型。

// 0.13
#[derive(Event, Component)]
struct MyEvent;

// 0.14
// `Component` is still implemented by the `Event` derive.
#[derive(Event)]
struct MyEvent;

有关更多信息，请参阅有关钩子和观察者的 发行说明。

在 System::run 中立即应用延迟的系统参数 #

• PR #11823
• ECS

System::run 的默认实现现在将始终立即运行 System::apply_deferred。如果您在此情况下手动调用 System::apply_deferred，您可能需要将其移除。请注意，System::run_unsafe 仍然 *不会* 调用 apply_deferred，因为它无法保证它是安全的。

// 0.13
system.run(world);

// Sometime later:
system.apply_deferred(world);

// 0.14
system.run(world);

// `apply_deferred` no longer needs to be called!

将 Command 和 CommandQueue 移动到 bevy::ecs::world #

• PR #12234
• ECS

Command 和 CommandQueue 已从 bevy::ecs::system 移动到 bevy::ecs::world。如果您直接导入它们，您需要更新您的导入语句。

// 0.13
use bevy::ecs::system::{Command, CommandQueue};

// 0.14
use bevy::ecs::world::{Command, CommandQueue};

使 Component::Storage 成为一个常量 #

• PR #12311
• ECS

Component::Storage 关联类型已被关联常量 STORAGE_TYPE 替换，从而使 ComponentStorage 特征不再必要。如果您手动实现 Component 而不是使用 derive 宏，请更新您的定义。

// 0.13
impl Component for MyComponent {
    type Storage = TableStorage;
}

// 0.14
impl Component for MyComponent {
    const STORAGE_TYPE: StorageType = StorageType::Table;

    // ...
}

Component 现在也不再是对象安全的。如果您使用过 dyn Component，请考虑 提交一个问题 来描述您的用例。

不要在 QueryState 中存储 Access<ArchetypeComponentId> #

• PR #12474
• ECS

QueryState 不再存储 Access<ArchetypeComponentId>，您现在必须将其作为参数传递给使用它的每个方法。为了解决此更改

• QueryState::archetype_component_access 已被移除。您可以通过访问周围的 SystemState 来解决此问题。
• QueryState::new_archetype 和 QueryState::update_archetype_component_access 现在需要 &mut Access<ArchetypeComponentId> 作为参数。

移除 WorldCell #

• PR #12551
• ECS

WorldCell 由于其不完整性、容易产生运行时恐慌以及存在多种良好替代方案而被移除。如果您使用它来获取多个不同的资源值，请考虑改用 SystemState，使用 SystemState::get() 方法。

如果 SystemState 不适合您的用例并且可以容忍 unsafe，您可以使用 UnsafeWorldCell。它更高效、功能更强大，但缺乏运行时检查。

为 QueryState::matched_tables 和 QueryState::matches_archtypes 返回迭代器而不是切片 #

• PR #12476
• ECS

QueryState::matched_tables 和 QueryState::matched_archetypes 现在返回迭代器而不是切片。如果可能，请使用来自 Iterator 特征的组合器。在最坏的情况下，您可以调用 Iterator::collect() 转换为 Vec，然后可以将其转换为切片。

从默认特征中移除系统步进 #

• PR #12847
• ECS

系统步进功能现在默认情况下处于禁用状态。它通常不应该包含在发布的游戏中，并且会增加一小部分但可衡量的性能开销。要启用它，请将 bevy_debug_stepping 功能添加到您的 Cargo.toml 中。

[dependencies]
bevy = { version = "0.14", features = ["bevy_debug_stepping"] }

使用 Stepping 的代码仍然可以在该功能被禁用时编译，但在应用程序调用 Stepping::enable() 时会在运行时打印一条错误消息。

优化事件更新和虚拟时间 #

• PR #12936
• ECS

Events::update() 已被优化为对注册的事件数量为 O(1)。在此过程中，一些系统和运行条件也发生了变化。

使用 EventRegistry 而不是 Events 资源将事件注册到 World 中。

// 0.13
world.insert_resource(Events::<MyEvent>::default());

// 0.14
EventRegistry::register_event::<MyEvent>(&mut world);

一些系统和运行条件也发生了变化。

• event_update_system 不再使用泛型，并且现在具有不同的参数。
• signal_event_update_system 现在具有不同的参数。
• reset_event_update_signal_system 已被移除。
• event_update_condition 现在具有不同的参数。

虽然与事件无关，但 virtual_time_system 也发生了变化。它已从一个系统转换为一个常规函数，并且现在接受 &T 和 &mut T 而不是 Res<T> 和 ResMut<T>。

使 SystemParam::new_archetype 和 QueryState::new_archetype 不安全 #

• PR #13044
• ECS

QueryState::new_archetype 和 SystemParam::new_archetype 现在是不安全的函数，因为它们不能确保提供的 Archetype 来自与状态初始化所在的同一个 World。您需要将任何用法包装在 unsafe 块中，并且可能需要编写额外的断言以验证正确的用法。

更好的 SystemId 和 Entity 转换 #

• PR #13090
• ECS

如果您需要访问一次性系统的 SystemId 的底层 Entity，请使用新的 SystemId::entity() 方法。

// 0.13
let system_id = world.register_system(my_system);
let entity = Entity::from(system_id);

// 0.14
let system_id = world.register_system(my_system);
let entity = system_id.entity();

使 NextState 成为一个枚举 #

• PR #11426
• ECS

NextState 已从单元结构体转换为枚举。如果您直接访问内部 Option，无论是通过 NextState::0 还是匹配，您将需要更新您的代码以处理此更改。

// 0.13
let state = next_state.0.unwrap();

// 0.14
let NextState::Pending(state) = next_state else { panic!("No pending next state!") };

将状态与核心 ECS 分开 #

• PR #13216
• ECS

状态已移至一个独立的 crate，该 crate 受 bevy_state 特性控制。使用状态但未使用 Bevy 的 default-features 的项目需要将此特性添加到其 Cargo.toml 中。

直接使用 bevy_ecs 并使用状态的项目需要添加 bevy_state **crate** 作为依赖项。

直接使用 bevy_app 并使用状态的项目需要添加 bevy_state **特性**。

如果您不使用 DefaultPlugins，您将需要手动将 StatesPlugin 添加到您的应用程序中。

用户应更新引用旧位置的导入。

// 0.13
use bevy::ecs::schedule::{NextState, OnEnter, OnExit, OnTransition, State, States};
use bevy::ecs::schedule::common_conditions::in_state;

// 0.14
use bevy::state::state::{NextState, OnEnter, OnExit, OnTransition, State, States}
use bevy::state::condition::in_state;

将 WorldQuery::get_state() 限制为仅接受 Components #

• PR #13343
• ECS

WorldQuery 和 QueryState 的一些方法是不安全的，因为它们传递了一个 &World。现在它们被限制为只接受 &Components。受影响的方法是

• WorldQuery::get_state()
• QueryState::transmute()
• QueryState::transmute_filtered()
• QueryState::join()
• QueryState::join_filtered()

要从 World 中访问 Components，请调用 World::components()。

如果您手动实现了 WorldQuery，则需要更新 get_state() 以仅使用 Components 提供的信息。

将状态转换名称统一为 exited 和 entered #

• PR #13594
• ECS

StateTransitionEvent 的 before 和 after 字段已重命名为 exited 和 entered 以保持一致性。如果您访问这些字段或构造 StateTransitionEvent，则需要更新您的使用方式。

使 apply_state_transition 变为私有 #

• PR #13626
• ECS

apply_state_transition 系统不再公开。迁移依赖它的系统的最简单方法是创建一个自定义调度。

// 0.13
App::new()
    .add_plugins(DefaultPlugins)
    .add_systems(StateTransition, my_system.after(apply_state_transition))
    .run()

// 0.14
#[derive(ScheduleLabel, Debug, Hash, PartialEq, Eq, Clone)]
struct AfterStateTransition;

let mut app = App::new();

app.add_plugins(DefaultPlugins)
    .add_systems(AfterStateTransition, my_system);

// Create a new schedule and add it to the app.
let after_state_transition = Schedule::new(AfterStateTransition);
app.add_schedule(after_state_transition);

// Modify the schedule order to make this run after `StateTransition`.
app.world_mut()
    .resource_mut::<MainScheduleOrder>()
    .insert_after(StateTransition, AfterStateTransition);

app.run()

用 ReflectResource 上的 FromReflect 替换 FromWorld 要求 #

• PR #12136
• ECS
• 反射

#[reflect(Resource)] 现在要求为您的资源实现 FromReflect 特性。如果您使用 #[derive(Reflect)]，则默认情况下会执行此操作，但是您选择退出此行为的结构体将需要编写自己的实现。FromReflect 已被添加来替换 FromWorld 要求，尽管 FromReflect 是可失败的。您可能希望将 #[reflect(FromWorld)] 添加到您的资源中以维护一个不可失败的变体。

最后，如果您使用 ReflectResource 结构体，则需要将 &TypeRegistry 传递给其 insert、apply_or_insert 和 copy 方法。

使 ReflectComponentFns 和 ReflectBundleFns 方法与 EntityMut 协同工作 #

• PR #12895
• ECS
• 反射

ReflectComponentFns 和 ReflectBundleFns 已更新为与 EntityMut 协同工作，与更严格的 EntityWorldMut 相比。您将需要更新您对 ReflectComponentFns::apply、ReflectComponentFns::reflect_mut 和 ReflectBundleFns::apply 的使用。

如果您只使用 ReflectComponent 和 ReflectBundle，则不需要更改代码，因为 EntityWorldMut 实现了 Into<EntityMut>。

在 ReflectBundle::insert() 中要求 TypeRegistry #

• PR #12499
• ECS
• 反射

ReflectBundle::insert 现在需要一个额外的 &TypeRegistry 参数。

将 multi-threaded 特性重命名为 multi_threaded #

• PR #12997
• ECS
• 任务

multi-threaded 特性已为 bevy、bevy_asset、bevy_ecs、bevy_render、bevy_tasks 和 bevy_internal 重命名为 multi_threaded。如果您手动指定 Bevy 特性，请更新您的 Cargo.toml。

将 intern 和 label 模块从 bevy::utils 移至 bevy::ecs #

• PR #12772
• ECS
• 实用程序

bevy::utils::label 和 bevy::utils::intern 模块已移至 bevy::ecs，以及 bevy::utils::define_label 宏，作为缩减 bevy::utils 的一项积极努力的一部分。您将需要更新您的导入语句以使用新的路径。

Gizmos #

Gizmo 线连接 #

• PR #12252
• Gizmos

已为 gizmos 添加了线连接，允许在直线之间创建圆角或尖角。如果您手动创建了自己的 GizmoConfig，则需要使用 line_joins 字段指定线连接的类型。

GizmoLineJoint 的 Default 实现为 None，但您可能对 Miter（尖角）或 Round（圆角）感兴趣。

Gizmo 线样式 #

• PR #12394
• Gizmos

现在可以使用 GizmoConfig::line_style 配置 gizmos 的线样式（例如实线或点线）。如果您手动创建一个 GizmoConfig，则需要指定此字段。

将 segments() 方法重命名为 resolution() #

• PR #13438
• Gizmos

所有名为 segments() 的 gizmo 方法已重命名为 resolution()，以与 bevy::render 保持一致。

使 gizmos 以引用方式获取基元 #

• PR #13534
• Gizmos

Gizmos::primitive_2d() 和 Gizmos::primitive_3d() 现在以引用方式获取基元，这样非 Copy 基元就不需要在每次绘制时进行克隆。

// 0.13
fn draw(mut gizmos: Gizmos) {
    let polygon = Polygon {
        vertices: [
            // ...
        ],
    };

    // Since `Polygon` is not `Copy`, you would need to clone it if you use it more than once.
    gizmos.primitive_2d(polygon.clone(), Vec2::ZERO, 0.0, Color::WHITE);
    gizmos.primitive_2d(polygon, Vec2::ONE, 0.0, Color::BLACK);
}

// 0.14
fn draw(mut gizmos: Gizmos) {
    let polygon = Polygon {
        vertices: [
            // ...
        ],
    };

    // No need to clone the polygon anymore!
    gizmos.primitive_2d(&polygon, Vec2::ZERO, 0.0, Color::WHITE);
    gizmos.primitive_2d(&polygon, Vec2::ONE, 0.0, Color::BLACK);
}

更多 gizmos 生成器 #

• PR #13261
• Gizmos

Gizmos::primitive_2d(CIRLCE)、Gizmos::primitive_2d(ELLIPSE)、Gizmos::primitive_2d(ANNULUS) 和 Gizmos::primitive_3d(SPHERE) 现在返回其相应的生成器，而不是单元类型 ()。此外，SphereBuilder::circle_segments() 已重命名为 resolution()。

上下文清除 gizmos #

• PR #10973
• Gizmos

App::insert_gizmo_group() 函数现在名为 App::insert_gizmo_config()。

输入 #

将触控板输入重命名为手势 #

• PR #13660
• 输入

在最近的 winit 更新中，触控板事件现在可以在移动设备上触发。为了解决这个问题，与触控板相关的项目已重命名为手势

• bevy::input::touchpad 已重命名为 bevy::input::gestures。
• TouchpadMagnify 已重命名为 PinchGesture。
• TouchpadRotate 已重命名为 RotationGesture。

弃用 ReceivedCharacter #

• PR #12868
• 输入
• 窗口化

ReceivedCharacter 现在已弃用，因为 winit 重构了其键盘系统，请改为使用 KeyboardInput。

// 0.13
fn listen_characters(events: EventReader<ReceivedCharacter>) {
    for event in events.read() {
        info!("{}", event.char);
    }
}

// 0.14
fn listen_characters(events: EventReader<KeyboardInput>) {
    for event in events.read() {
        // Only check for characters when the key is pressed.
        if !event.state.is_pressed() {
            continue;
        }

        // Note that some keys such as `Space` and `Tab` won't be detected as a character.
        // Instead, check for them as separate enum variants.
        match &event.logical_key {
            Key::Character(character) => {
                info!("{} pressed.", character);
            },
            Key::Space => {
                info!("Space pressed.");
            },
            _ => {},
        }
    }
}

添加 WinitEvent::KeyboardFocusLost #

• PR #13678
• 输入
• 窗口化

WinitEvent 有一个新的枚举变体：WinitEvent::KeyboardFocusLost。这是在修复失去 Bevy 窗口焦点时（例如使用 Alt + Tab）按键会卡住问题时添加的。请更新所有 match 语句。

数学 #

将有限和无限 3d 平面分开 #

• PR #12426
• 数学
• 渲染

Plane3d 基元现在是一个有限平面，具有 half_size 字段。如果您想要一个无限平面，请使用新的 InfinitePlane3d。

// 0.13
let plane = Plane3d::new(Vec3::Y);

// 0.14
let plane = Plane3d {
    normal: Dir3::Y,
    half_size: Vec2::new(10., 10.),
};
let plane = InfinitePlane3d::new(Vec3::Y);

将方向类型从 bevy::math::primitives 中移出 #

• PR #12018
• 数学

Direction2d、Direction3d 和 InvalidDirectionError 类型已从 bevy::math::primitives 移至 bevy::math。

// 0.13
use bevy::math::primitives::{Direction2d, Direction3d, InvalidDirectionError};

// 0.14
use bevy::math::{Direction2d, Direction3d, InvalidDirectionError};

将 Direction2d/3d 重命名为 Dir2/3 #

• PR #12189
• 数学

Direction2d 和 Direction3d 类型已重命名为 Dir2 和 Dir3。它们已缩短，使其更容易键入，并使其与 glam 的较短命名方案（例如 Vec2、Mat4）保持一致。

使基点样条曲线包含端点 #

• PR #12574
• 数学

CubicCardinalSpline 中存在一个错误，该错误导致曲线仅穿过内部控制点，而不是起点和终点处的点。（有关深入分析，请参阅 此问题。）此问题已修复，因此曲线穿过所有控制点，但它可能会破坏您依赖的行为。

如果您依赖 CubicCardinalSpline 的旧行为，则需要截断您使用的任何参数化，以便访问与您之前使用的曲线相同的曲线。这可以通过从参数化区间的每个端点裁剪一个单位距离段来完成。例如，如果您的代码如下所示

fn interpolate(t: f32) -> Vec2 {
    let points = [
        vec2(-1.0, -20.0),
        vec2(3.0, 2.0),
        vec2(5.0, 3.0),
        vec2(9.0, 8.0),
    ];
    let my_curve = CubicCardinalSpline::new(0.3, points).to_curve();
    my_curve.position(t)
}

然后为了获得类似的行为，t 需要向上移动 1 个单位（因为 CubicCardinalSpline::to_curve 的输出在区间 [0,1] 中引入了一个新段），将旧段从 [0,1] 移动到 [1,2]

fn interpolate(t: f32) -> Vec2 {
    let points = [
        vec2(-1.0, -20.0),
        vec2(3.0, 2.0),
        vec2(5.0, 3.0),
        vec2(9.0, 8.0),
    ];
    let my_curve = CubicCardinalSpline::new(0.3, points).to_curve();
    // Add 1 here to restore original behavior.
    my_curve.position(t + 1)
}

（请注意，这不会为 t 的值提供相同的输出，这些值位于区间 [0,1] 之外。）

另一方面，任何只为了让曲线穿过正确点（即不需要完全相同的输出）而指定额外端点切线的用户，都可以简单地省略只用于控制目的的端点。

用 VectorSpace 替换 Point #

• PR #12747
• 数学

Point 特性已被 VectorSpace 替换。这些特性非常相似，但有一些细微的改变

• VectorSpace 实现现在必须提供 ZERO 常量。
• VectorSpace 现在需要 Div<f32, Output = Self> 和 Neg 特性边界。
• VectorSpace 不再需要 Add<f32, Output = Self>、Sum 和 PartialEq 特性边界。

对于大多数情况，您可以用 VectorSpace 替换所有 Point 使用情况，但如果您依赖上述列表中的任何内容，则可能需要进行进一步的更改。

Triangle2d 的 UV 映射更改 #

• PR #12686
• 数学

通过此 PR，Triangle2d 的 UV 映射已更改：主要区别在于 UV 不再依赖于三角形的绝对坐标，而是遵循三角形本身在其定义中的平移。如果您依赖于 Triangle2d 的旧 UV 坐标，那么您将需要更新受影响的区域以使用新的 UV 坐标，这些 UV 坐标可以简要描述如下

• 第一个坐标平行于三角形的前两个顶点之间的线。
• 第二个坐标与此正交，指向第三个点的方向。

一般来说，这意味着前两个点的坐标将为[_, 0.]，而第三个点的坐标将为[_, 1.]，其具体值取决于第三个点相对于前两个点的 位置。对于锐角三角形，前两个顶点始终具有 UV 坐标[0., 0.]和[1., 0.]。对于钝角三角形，第三个点将具有坐标[0., 1.]或[1., 1.]，其中另一个点的坐标会发生变化，以保持比例。

例如

• 默认的 Triangle2d 的 UV 坐标为[0., 0.]、[0., 1.] 和[0.5, 1.]。
• 顶点为vec2(0., 0.)、vec2(1., 0.) 和vec2(2., 1.)的三角形具有 UV 坐标[0., 0.]、[0.5, 0.] 和[1., 1.]。
• 顶点为vec2(0., 0.)、vec2(1., 0.) 和vec2(-2., 1.)的三角形具有 UV 坐标[2./3., 0.]、[1., 0.] 和[0., 1.]。

使用 Vec3A 用于 3D 包围盒和射线检测 #

• PR #13087
• 数学

Aabb3d、BoundingSphere 和RayCast3d 现在在内部使用Vec3A 而不是Vec3。Vec3A 是Vec3 的 SIMD 加速形式，因此它应该在不明显改变行为的情况下提高性能。

如果你手动构建任何受影响的结构，则需要将其转换为Vec3A。

// 0.13
let x = Vec3::new(5.0, -2.0);

let aabb = Aabb3d {
    min: Vec3::ZERO,
    max: x,
};

// 0.14
let x = Vec3::new(5.0, -2.0);

let aabb = Aabb3d {
    // Both variants are very similar, so you can usually replace `Vec3` with `Vec3A`.
    min: Vec3A::ZERO,
    // In cases where you cannot, use the `From` and `Into` traits.
    max: x.into(),
};

将 glam 更新到 0.27 #

• PR #12757
• 数学

glam 已从 0.25 更新到 0.27。请查看变更日志了解 0.26 和 0.27，以便更新你的代码。

最大的破坏性变化是，向量类型现在以self - self.trunc() 而不是self - self.floor() 的形式评估fract() 方法。如果你需要旧行为，请使用fract_gl() 方法。

公共 MeshBuilder 特性 #

• PR #13411
• 数学
• 渲染

所有形状网格构建器（ConeMeshBuilder、PlaneMeshBuilder 等）都具有一个方法build()，用于将它们转换为Mesh。此方法已成为公共特性MeshBuilder。如果你使用build() 但未使用预置，则需要导入此特性。

向 TorusMeshBuilder 添加角度范围 #

• PR #13605
• 数学
• 渲染

TorusMeshBuilder 不再是Copy，因为它包含用于角度范围的RangeInclusive（x..=y）。在以前隐式复制它的任何情况下，都需要手动调用clone()。

向 PlaneMeshBuilder 添加细分 #

• PR #13580
• 数学
• 渲染

在 0.13 中，Plane 类型已被弃用，取而代之的是Plane2d 和Plane3d。新的平面类型没有提供用于细分的方法，现已进行修订。

如果你使用了Plane::subdivisions 属性，现在需要将Plane3d 转换为PlaneMeshBuilder。

// 0.13
let plane = Plane {
    subdivisions: 10,
    ..default()
};

// 0.14
let plane = Plane3d::default().mesh().subdivisions(10);

使 Transform::rotate_axis 和 Transform::rotate_local_axis 使用 Dir3 #

• PR #12986
• 数学
• 变换

Transform::rotate_axis() 和Transform::rotate_local_axis() 现在需要Dir3 而不是Vec3，因为轴预计是标准化的。通常，你可以使用Vec3 调用Dir3::new()，它会自动将其标准化，但你必须处理Result，以防向量无效。

请注意，大多数常量（如Vec3::X）都具有相应的Dir3 变体，如Dir3::X。

在 GlobalTransform 中使用 Dir3 用于局部轴方法 #

• PR #13264
• 数学
• 变换

GlobalTransform 组件的定向轴方法（right()、left()、up()、down()、back()、forward()）已从返回Vec3 更新为返回Dir3。Dir3 实现Deref<Target = Vec>，但如果你需要可变访问，则可以调用Vec3::from()。

修复 FloatOrd 的 Ord 和 PartialOrd 不同 #

• PR #12711
• 数学
• 实用程序

FloatOrd 的PartialOrd 实现以前在行为上与其Ord 实现不同，但现在已修复，因此两者现在都匹配。PartialOrd 的当前实现永远不会返回None，因为它现在回退到Ord 实现。如果你依赖于这种不匹配的行为，请考虑对内部的f32 使用PartialOrd 实现。

将 FloatOrd 移动到 bevy::math #

• PR #12732
• 数学
• 实用程序

FloatOrd 已被移动到bevy::math 模块中。请更新你的导入语句

// 0.13
use bevy::utils::FloatOrd;

// 0.14
use bevy::math::FloatOrd;

反射 #

手动注册缺失类型 #

• PR #12314
• 反射

许多外部类型不再由 Bevy 的默认插件注册到类型注册表中。通常，只有其他 Bevy 类型使用的类型（由于新的递归注册）才会默认注册。如果你以前在std 或glam 中使用过类型进行反射功能，则可能需要手动注册它们。

App::new().register_type::<DMat3>();

更改 ReflectSerialize 特性边界 #

• PR #12024
• 反射

ReflectSerialize 现在需要TypePath 和FromReflect 特性边界，而不是Reflect。如果你以前选择退出它们，则需要实现这些特性。例如，如果你使用了#[reflect(type_path = false)] 或#[reflect(from_reflect = false)]，则需要删除它们。

类型的递归注册 #

• PR #5781
• 反射

现在可以递归注册类型，但在这样做时，所有（未忽略的）反射字段都需要实现GetTypeRegistration。当Reflect 被派生时，会自动完成此操作，但手动实现还需要实现GetTypeRegistration。

#[derive(Reflect)]
struct Foo<T: FromReflect> {
    data: MyCustomType<T>
}

// 0.13
impl<T: FromReflect> Reflect for MyCustomType<T> {
    // ...
}

// 0.14
impl<T: FromReflect + GetTypeRegistration> Reflect for MyCustomType<T> {
    // ...
}

impl<T: FromReflect + GetTypeRegistration> GetTypeRegistration for MyCustomType<T> {
    // ...
}