bevy-migration-0-17-to-0-18

Bevy 0.17 → 0.18 — 迁移速查表

发布于 2026-01-13。 按顺序从上到下应用——跳过前面的项目会导致后续构建失败。

何时使用此技能

• 将 bevy = "0.17" 升级为 bevy = "0.18" 后出现编译器错误。
• LLM 根据训练数据生成了 0.17 时代的 API 名称。
• 审查 PR，检查是否存在隐蔽的 0.18 不兼容模式。
• 为尚未发布 0.18 的下游 crate 紧急修复。

最先遇到的重命名

观察器：Trigger<E> → On<E>

// 0.18 (also 0.17)
fn on_hit(on: On<Damage>) { let _e = on.event(); }

缓冲事件：Event → Message

// 0.18
#[derive(Message)] struct Tick;
// app.add_message::<Tick>();
fn read(mut reader: MessageReader<Tick>) { for _ in reader.read() {} }
fn write(mut w: MessageWriter<Tick>) { w.write(Tick); }

现在，Event 专用于被观察、以实体为目标的事件（#[derive(EntityEvent)]）。

Camera { target: ... } → RenderTarget 组件

// 0.18
commands.spawn((Camera3d::default(), RenderTarget::Image(handle.into())));

AmbientLight 不再是资源

// 0.18: global default
app.insert_resource(GlobalAmbientLight { brightness: 2000.0, ..default() });
// Per-camera override:
commands.spawn((Camera3d::default(), AmbientLight { brightness: 5000.0, ..default() }));

MaterialPlugin<M> 的配置移至 trait 方法

// 0.18
impl Material for M {
    fn enable_prepass() -> bool { false }
    fn enable_shadows() -> bool { false }
}
app.add_plugins(MaterialPlugin::<M>::default());

现在必须实现 AsBindGroup::label()

impl AsBindGroup for MyMaterial {
    fn label() -> &'static str { "MyMaterial" }
}

AssetLoader 必须 #[derive(TypePath)]

#[derive(TypePath)]
struct MyLoader;
impl AssetLoader for MyLoader { /* ... */ }

Mesh::insert_attribute 可能引发 panic——建议使用 try_insert_attribute

// 0.18 safe form — returns Result<(), MeshAccessError>
mesh.try_insert_attribute(Mesh::ATTRIBUTE_POSITION, positions)?;

State::set 总会触发状态转换

// 0.18: always fires OnExit + OnEnter. Guard with:
next_state.set_if_neq(GameState::Playing);

glTF 坐标转换已替换

// 0.18
GltfPlugin {
    convert_coordinates: GltfConvertCoordinates {
        rotate_scene_entity: true,
        rotate_meshes: true,
    },
    ..default()
}

调度执行器

SimpleExecutor 已移除。 如果后续系统必须在同一调度中观察到先前系统发出的命令，请添加 .before()、.after() 或 .chain()。其余执行器会利用这些依赖来放置 ApplyDeferred；歧义检测仍可单独配置。参见 references/schedule-renames.md。

主题

主题	参考
On<E>、MessageReader/MessageWriter、Entity::index、tick 迁移、Resource 'static、反射语法、层级辅助工具	references/ecs-renames.md
RenderTarget 组件、GlobalAmbientLight、MaterialPlugin、AsBindGroup::label、gizmos、bevy_gizmos_render 拆分	references/render-renames.md
AssetLoader + TypePath、LoadContext::asset_path、asset_bytes 读取器模式、AssetSource 通道、try_insert_attribute	references/asset-renames.md
移除 SimpleExecutor、ScheduleBuildError 变体、State::set 总会触发、or 组合器、glTF 坐标	references/schedule-renames.md
animation → gltf_animation、picking 后端重命名、documentation → reflect_documentation、输入选择启用	references/cargo-feature-renames.md

注意事项

• bevy_gizmos 已拆分。 渲染端代码现位于 bevy_gizmos_render。如果使用了内部功能，请更新导入路径。
• Resource 不再允许非 'static 生命周期。 含有借用字段的 Resource 将无法编译。
• 反射属性语法已收紧。 只接受 #[reflect(...)]（圆括号）；花括号和方括号形式均不接受。
• AnimationTarget 已拆分为两个组件。 使用 (AnimationTargetId(id), AnimatedBy(player))。
• Atmosphere 现在引用 Handle<ScatteringMedium>——原本的平面结构体现在改为间接引用。

另请参阅

• bevy-migration-0-18-to-0-19 — 下一个版本的重命名目录。
• bevy-core-concepts — 调度执行器变更的详细说明。
• bevy-cargo-features — 功能重命名表。
• bevy-ecs-systems — Message/MessageReader/MessageWriter 的易用性说明。