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 をリリースしていない下流クレートを、緊急修正するとき。

最初に直面するリネーム

オブザーバー：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> の設定はトレイトメソッドに移動しました

// 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 はパニックする可能性があります — 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、ティックの移動、Resource 'static、リフレクトの構文、階層ヘルパー	references/ecs-renames.md
RenderTarget コンポーネント、GlobalAmbientLight、MaterialPlugin、AsBindGroup::label、ギズモ、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、ピッキングバックエンドのリネーム、documentation → reflect_documentation、入力のオプトイン	references/cargo-feature-renames.md

注意点

• bevy_gizmos は分割されました。 描画側のコードは bevy_gizmos_render に移動しました。内部機能を使っていた場合は、インポートパスを更新してください。
• Resource は 'static 以外のライフタイムを許可しなくなりました。 借用フィールドを持つ Resource はコンパイルに失敗します。
• リフレクト属性の構文が厳格化されました。 #[reflect(...)]（括弧形式）のみ受け付けられ、波括弧や角括弧の形式は拒否されます。
• AnimationTarget は2つのコンポーネントに分割されました。 (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 の使い勝手。