Rust Bevy 0.13 到 0.14 升级踩坑指南

🚨 重要提醒

本文记录将一个 Bevy 0.13 的 2D 像素游戏升级到 0.14 版本的全过程踩坑记录。0.14 是作者在 macOS 上运行最稳定的版本（更高版本会出现黑屏问题），因此锁定此版本。升级后，还顺手将项目中从 Python 迁移过来的两个模块（调试控制台和剧本系统）进行了补充。

一、为什么是 0.14

• macOS 兼容性：0.15 及以上版本在 macOS 上存在黑屏问题，0.14 是目前最稳定的选择。
• 破坏性变更：0.13 → 0.14 存在破坏性 API 变更，不能仅仅修改 Cargo.toml 中的版本号。

二、Cargo.toml 的三处改动

1. 版本号

# before bevy = { version = "0.13", default-features = false, features = [...] } after bevy = { version = "0.14", default-features = false, features = [...] }

2. feature 名改了下划线大小写

# 0.13 用 hyphen-case "multi-threaded", 0.14 改成 snake_case "multi_threaded",

运行cargo fetch会直接报错：

package depends on `bevy` with feature `multi-threaded` but `bevy` does not have that feature. help: there is a feature `multi_threaded` with a similar name

按照提示修改即可。

3. 诊断插件 feature 改了名

# 0.13 "bevy_diagnostic", # ❌ 0.14 没这个 feature 0.14 "bevy_dev_tools", # ✅ FrameTimeDiagnosticsPlugin 跟着这个来

报错会列出全部可用 feature，从里面挑选即可。

4. 显式加 bevy_state / bevy_app 依赖

这是default-features = false项目的专属坑——详见下一节。

三、State API：最大的坑

症状

升级后一编译就刷出一屏幕错误：

error: cannot find derive macro `States` in this scope error[E0425]: cannot find type `NextState` in this scope error[E0425]: cannot find function `in_state` in this scope error[E0425]: cannot find `OnEnter` / `OnExit` error[E0599]: no method named `init_state` found for `&mut App` error[E0599]: no method named `enable_state` found for `&mut App`

根因

0.14 把 state 系统移出了bevy::prelude，迁移到了独立的 cratebevy_state。bevy通过bevy_internal重命名 re-export：

// bevy_internal/src/lib.rs #[cfg(feature = "bevy_state")] pub use bevy_state as state;

所以bevy::state这条路径理论上还在，但需要开启bevy_statefeature。而我们使用了default-features = false，默认的 feature 集被砍掉了——0.13 时 state 跟着 prelude 走，0.14 必须显式开启。

解法（三步）

第一步：Cargo.toml 开 feature + 加依赖

bevy = { version = "0.14", default-features = false, features = [ ..., "bevy_state", # 激活 bevy::state re-export ] } 单开 bevy_state feature 还不够，AppExtStates（含 init_state）在 bevy_state::app 里， 它 use bevy_app::{App, ...}。所以要把 bevy_app 也拉进依赖图。 bevy_state = "0.14" bevy_app = "0.14"

第二步：import 路径全部改走bevy_state

// ❌ 0.13：靠 prelude 自动可用 #[derive(States, Debug, Clone, Copy, PartialEq, Eq, Hash, Default)] pub enum GameState { ... } .add_systems(OnEnter(GameState::Playing), ...) .add_systems(Update, foo.run_if(in_state(GameState::Playing))) .next_state.set(GameState::GameOver);

// ✅ 0.14：全部 explicit import use bevy_state::app::AppExtStates; // 含 init_state use bevy_state::state::{OnEnter, OnExit, States, NextState}; use bevy_state::condition::in_state;

每个用到NextState的文件都要加一行：

use bevy_state::state::NextState;

第三步：删掉enable_state调用

// ❌ 0.13 写法 .init_state::<GameState>() .enable_state::<GameState>() // 0.14 砍了这方法

// ✅ 0.14：init_state 单独够用（内部已 setup transitions） .init_state::<GameState>()

验证路径是否正确的最小用例

升级时我先在/tmp里创建一个小的 cargo 项目验证 import 路径，再回主项目修改：

use bevy::prelude::*; use bevy_state::app::AppExtStates; use bevy_state::state::{OnEnter, OnExit, States, NextState}; use bevy_state::condition::in_state; #[derive(States, Debug, Clone, Copy, PartialEq, Eq, Hash, Default)] pub enum S { #[default] A, B } fn main() { App::new() .init_state::<S>() .add_systems(OnEnter(S::A), || {}) .add_systems(OnExit(S::A), || {}) .add_systems(Update, (|| {}).run_if(in_state(S::A))) .run(); }

运行cargo check通过后再回主项目批量修改——比直接在主项目里试错快得多。

AppExtStates 的可用方法（0.14）

enable_state被砍掉之后，我查阅了bevy_state::app::AppExtStates的完整方法表，确认 0.14 只剩这些：

四、Mesh::from(shape::Circle) 的 shape 模块消失

症状

error[E0433]: cannot find module or crate `shape` in this scope

根因

0.13 的bevy::sprite::shape::Circle { radius, vertices }在 0.14 被移走了。0.14 把几何图元迁移到了bevy_math::primitives，且Circle结构体砍掉了vertices字段，只剩radius：

// bevy_math 0.14 pub struct Circle { pub radius: f32, }

解法

// ❌ 0.13 use bevy::prelude::*; // shape 跟着 prelude 走 let mesh = meshes.add(Mesh::from(shape::Circle { radius: 32.0, vertices: 32 })); // ✅ 0.14：显式 import + 去掉 vertices 字段 use bevy::math::primitives::Circle; let mesh = meshes.add(Mesh::from(Circle { radius: 32.0 })); // From<Circle> for Mesh 仍存在，默认 32 分辨率

如果想要自定义分辨率，用 builder 链：

use bevy::math::primitives::Circle; use bevy::render::mesh:: primitives::Meshable; // trait .mesh() let mesh = meshes.add(Circle { radius: 32.0 }.mesh().resolution(64).build());

五、Color 分量访问：.r() .g() .b() .a() 全砍

症状

error[E0599]: no method named `r` found for struct `Color` in the current scope error[E0599]: no method named `g` found for struct `Color` in the current scope error[E0599]: no method named `b` found for struct `Color` in the current scope error[E0599]: no method named `a` found for struct `Color` in the current scope

根因

0.13 的Color提供了.r(),.g(),.b(),.a()等 getter 方法。0.14 将这些方法全部移除，改为直接访问结构体字段。

解法

// ❌ 0.13 let color = Color::rgb(0.5, 0.2, 0.8); let red = color.r(); let alpha = color.a(); // ✅ 0.14：直接访问字段 let color = Color::rgb(0.5, 0.2, 0.8); let red = color.r; let alpha = color.a;

注意：Color的字段是公开的，可以直接读写。

六、其他常见变更与修复

1. 输入系统：KeyCode 枚举成员重命名

部分KeyCode枚举成员在 0.14 中被重命名，以符合更标准的命名约定。

// ❌ 0.13 KeyCode::LControl KeyCode::RControl // ✅ 0.14 KeyCode::ControlLeft KeyCode::ControlRight

类似的重命名也适用于其他修饰键（Shift, Alt, Meta/Command）。编译器会给出明确的错误提示，按照提示修改即可。

2. 精灵图集（TextureAtlas）布局 API 变更

创建TextureAtlas的 API 有所调整。

// ❌ 0.13 let atlas = TextureAtlas::from_grid( texture_handle, Vec2::new(16.0, 16.0), 4, 4, None, None, ); // ✅ 0.14 let atlas = TextureAtlas::from_grid( texture_handle, Vec2::new(16.0, 16.0), 4, 4, None, None, false, // 新增参数：是否填充空白区域 );

3. 相机投影（CameraProjection）相关变更

如果使用了自定义相机投影，可能需要更新 trait 实现。

// ❌ 0.13 impl CameraProjection for MyProjection { fn get_projection_matrix(&self) -> Mat4 { ... } fn update(&mut self, width: f32, height: f32) { ... } fn far(&self) -> f32 { ... } // ... } // ✅ 0.14 impl CameraProjection for MyProjection { fn get_projection_matrix(&self) -> Mat4 { ... } fn update(&mut self, width: f32, height: f32) { ... } // far 等方法可能已被移除或移至其他 trait，请查阅最新文档。 }

七、升级后补充模块：调试控制台与剧本系统

在成功升级到 Bevy 0.14 后，我顺手将项目中从 Python 原型迁移过来的两个核心模块进行了 Rust 重写和集成。

1. 调试控制台（Debug Console）

一个简单的内嵌式命令行界面，用于在游戏运行时执行命令、修改变量、打印状态。

// 主要功能 // - 按 ` 键呼出/隐藏控制台 // - 支持基本命令：spawn, teleport, godmode, fps // - 命令历史与自动补全 // - 输出日志滚动显示

2. 剧本系统（Script System）

一个基于事件的轻量级叙事与任务系统，用于驱动游戏剧情和角色对话。

// 核心组件 #[derive(Component)] pub struct Script { pub id: String, pub triggers: Vec<Trigger>, pub actions: Vec<Action>, } // 事件驱动 pub struct ScriptEvent { pub script_id: String, pub params: HashMap<String, String>, }

这两个模块的加入显著提升了项目的可调试性和内容创作灵活性。

八、总结

从 Bevy 0.13 升级到 0.14 主要挑战在于 State API 的抽离和一系列破坏性命名变更。关键步骤总结如下：

1. 修改 Cargo.toml：更新版本号，修正 feature 名称（如multi_threaded），并显式添加bevy_state和bevy_app依赖。
2. 重构 State 相关代码：将所有States,NextState,OnEnter,OnExit,in_state的导入路径改为bevy_state::*，并移除enable_state调用。
3. 更新几何图元：将shape::Circle等替换为bevy::math::primitives::Circle，注意字段变化。
4. 修正 Color 访问：将.r()等方法调用改为直接字段访问.r。
5. 处理其他 API 变更：如KeyCode重命名、TextureAtlasAPI 变更等。

升级过程虽然繁琐，但 0.14 在 macOS 上的稳定性提升是值得的。建议在升级前，在一个独立的小项目中验证关键变更，再回到主项目进行系统性的修改。