bevy

Bevy 0.20 — 路由器

使用 Bevy 项目时，请先阅读本文。 所有同级技能都假设使用 Bevy 0.20（0.20.0 于 2026-10-08 发布；当前补丁版本为 0.20.1，要求 rustc 1.97.1）。如果用户的 Cargo.toml 固定了其他版本，请先停止并确认，再应用此集合中的模式。

最小有效应用

use bevy::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_systems(Startup, setup)
        .run();
}

fn setup(mut commands: Commands) {
    commands.spawn(Camera3d::default());
}

应使用哪个技能

任务	技能
应用 / 插件 / 调度基础知识、Update 与 FixedUpdate 的区别、独占系统（0.20 中任何位置的 &mut World）	bevy-core-concepts
#[derive(Component)]、#[require(...)]、观察器（On<E>、On<Add<T>>）、钩子（on_add/on_discard）、存储	bevy-ecs-components
Query、With/Without/Or、Changed/Added、par_iter、iter_many(..).matched()、查询镜头	bevy-ecs-queries
SystemParam、SystemSet、.run_if、排序、.chain_weak()、remove_systems_in_set	bevy-ecs-systems
Cargo.toml 功能：2d/3d/ui、*_api、bevy_curve、compressed_image_saver*、WASM 精简	bevy-cargo-features
从 0.19 升级 — On<Add<T>>、PointerClick、Hovered/Pressed、WESL、set_if_different	bevy-migration-0-19-to-0-20
从 0.18 升级 — FontSource/FontSize、bevy_world_serialization、将资源用作组件	bevy-migration-0-18-to-0-19
从 0.17 升级 — MessageReader、On、RenderTarget、GlobalAmbientLight	bevy-migration-0-17-to-0-18
AssetServer、Handle<T>、load_builder、热重载、用于 glTF 场景的 WorldAssetRoot	bevy-assets
编写 AssetLoader（必须使用 Reader::seekable）	bevy-custom-assets
WASM 构建流程、WebGPU 与 WebGL2 的比较	bevy-wasm-webgpu
Camera3d、Projection、RenderTarget 组件、Tonemapping::Linear、ScreenSpaceTransmission、FreeCamera、PanCamera	bevy-cameras
StandardMaterial、MaterialPlugin<M>、AsBindGroup、WESL 自定义着色器、光照、氛围效果	bevy-pbr-materials
GPU 粒子（bevy_hanabi）、高斯泼溅、翻页动画、自定义 VFX 材质	bevy-vfx
AnimationPlayer、AnimationGraph、AnimationTransitions、AnimationMask、AnimationEvent、缓动曲线	bevy-animation
将摄像机录制为 MP4 或 PNG 序列（bevy_capture）	bevy-capture
使用 block-mesh-rs 生成体素网格、区块流程、贪心四边形	bevy-voxel-pipeline
RON 区块定义、调色板、KTX2 图集烘焙	bevy-voxel-data
可重新绑定的操作、实体 Gamepad、热插拔、死区、Steam Deck、将输入传入 FixedUpdate	bevy-input-actions
AudioPlayer、PlaybackSettings、AudioSink、空间监听器、混音组、浏览器解锁	bevy-audio
Rapier 刚体、碰撞体、固定步长排序、事件、场景查询、关节、确定性	bevy-physics
内置与外部 / 无头渲染、前向与延迟渲染、渲染系统	bevy-rendering
DiagnosticPath、DiagnosticsStore、info_span!、RenderDiagnosticsPlugin、CPU/GPU 计时	bevy-diagnostics-profiling
稳定 ID、带版本的保存 DTO、原子化的原生 / 浏览器写入、快照	bevy-save-load
确定性 App::update 步进、TimeUpdateStrategy、MessageCursor、无头测试	bevy-testing
屏幕阅读器、自适应控制器、重新映射、字幕、对比度、运动安全	bevy-a11y
体素编辑 → 运行时重新生成网格：脏区 / 光环扇出、修订令牌、有界上传	bevy-voxel-runtime
es-fluent-manager-bevy 国际化 — FluentText<T>、BevyFluentText、LocaleChangeEvent、i18n.toml	bevy-fluent
Node、ui_widgets::Button 与 Hovered/Pressed、children![]、TextFont/FontSize、Val::Em、Node::border_radius、InputFocus	bevy-ui
从 Unity、Unreal、Godot、Phaser、Flash、Defold、Roblox、GameMaker 移植	bevy-porting
提交前检测 Rust 代码中的复制粘贴 / 近似重复（similarity-rs --cross-file）	similarity-rs

核心规则（适用于每个 Bevy 0.20 任务）

1. 事件就是消息。 在 0.17 中，EventReader<E> / EventWriter<E> 已变为 MessageReader<M> / MessageWriter<M>。观察器使用 On<E>，而不是 Trigger<E>。
2. 生命周期观察器会在事件上携带 bundle。 使用 On<Add<Player>>，而不是 On<Add, Player>（在 0.20 中变更）。Replace 在 0.19 中变为 Discard。
3. 指针事件是扁平的。 使用 On<PointerClick>、click.pointer.position；而不是 On<Pointer<Click>>（0.20）。
4. UI 交互使用 Hovered + Pressed。 ui::Interaction 和 ui::widgets::Button 在 0.20 中已弃用；请生成 ui_widgets::Button。
5. 文本使用 FontSource + FontSize。 TextFont { font: handle.into(), font_size: FontSize::Px(24.0) }（0.19）。默认字号为 FontSize::Rem(1.)（0.20）。
6. 着色器使用 WESL。 使用 .wesl、import a::b;、@if(DEF)。naga_oil 的 #import / #ifdef 在 0.20 中会在资源加载时失败。
7. 资源就是组件（0.19）。Res<T> 仍然可用，但同一类型不能同时是 Component 和 Resource。
8. 场景： glTF 使用 bevy_world_serialization 中的 WorldAssetRoot 生成实体；bevy_scene 使用 BSN（0.19）。
9. 系统中不要使用 .unwrap()。 使用 let ... else { return }; 或真正的错误处理路径。
10. 调度顺序必须明确。 默认忽略歧义（ScheduleBuildSettings::ambiguity_detection 为 LogLevel::Ignore）；启用 LogLevel::Error 以检测歧义。0.20 中内置集合使用 .chain_weak()，因此需要通过通道或原子操作进行跨集合排序时，必须显式添加 .after()。

注意事项

• Bevy 训练数据中的代码主要来自 0.10–0.16。如果某段代码看起来显而易见，请先对照三个迁移技能进行核查，再决定是否采用。
• bevy::prelude::* 不会重新导出所有内容。Hovered 位于 bevy::picking::hover::Hovered；Pressed 是标记 bevy::ui::Pressed（使用 Has<Pressed> 查询）；Tonemapping 位于 bevy::core_pipeline::tonemapping::Tonemapping；ScreenSpaceTransmission 位于 bevy::pbr::ScreenSpaceTransmission。
• bevy crate 重新导出了许多子 crate（bevy_camera、bevy_light、bevy_material、bevy_extract、bevy_curve、bevy_shape、bevy_world_serialization、bevy_ui_widgets、bevy_feathers）。子 crate 的 API 是适用于插件的稳定依赖点。
• 弃用项（Interaction、set_if_neq、AssetId::invalid()）在 0.20 中会产生编译警告，之后将被移除。请现在修复。

另请参阅

• bevy-migration-0-19-to-0-20 — 最新的重命名和破坏性变更目录。
• bevy-cargo-features — 在上述内容按预期编译之前，Cargo.toml 中需要填写的内容。