bevy-ecs-components

Bevy 0.19 — ECS コンポーネント

このスキルを使う場面

• ゲームの状態を表す新しいComponentを定義する場合。
• #[require(...)]を使ってコンポーネントをまとめる場合（「バンドル」に代わる最新の方法です）。
• コンポーネントのライフサイクル（生成、破棄、挿入、削除）に反応する場合。
• オブザーバー：On<E>を使ってエンティティを対象とするイベントに反応する場合。
• ストレージを選択する場合：Table（デフォルトで、反復が高速）とSparseSet（追加・削除が高速）。

標準的なパターン

use bevy::prelude::*;

// 1. Plain components.
#[derive(Component, Default)]
struct Health(f32);

#[derive(Component)]
struct Velocity(Vec3);

// 2. Required components — spawning `Player` auto-spawns the rest.
//    `#[require]` accepts `Type` (Default), `Type(args)` (tuple constructor),
//    or `Type = expression`.
#[derive(Component)]
#[require(Health = Health(100.0), Velocity = Velocity(Vec3::ZERO), Transform)]
struct Player;

// 3. Sparse storage for components added/removed every frame (e.g. tags
//    flipped by gameplay). Default Table storage is faster to iterate.
#[derive(Component)]
#[component(storage = "SparseSet")]
struct Stunned;

// 4. An entity-targeted event reacted to by observers.
#[derive(EntityEvent)]
struct Damage {
    entity: Entity, // EntityEvent requires an `entity` field.
    amount: f32,
}

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_systems(Startup, spawn_player)
        .add_systems(Update, deal_damage)
        .add_observer(on_damage)
        .run();
}

fn spawn_player(mut commands: Commands) {
    commands.spawn(Player);
}

fn deal_damage(mut commands: Commands, query: Query<Entity, With<Player>>) {
    for entity in &query {
        commands.trigger(Damage { entity, amount: 10.0 });
    }
}

// Observer parameter is `On<E>`, not `Trigger<E>` (renamed in 0.17, PR #19596).
fn on_damage(damage: On<Damage>, mut query: Query<&mut Health>) {
    let event = damage.event();
    if let Ok(mut hp) = query.get_mut(event.entity) {
        hp.0 -= event.amount;
    }
}

Bevy 0.19 の注意点

• Trigger<E>は廃止されました。 オブザーバーのパラメーターは0.17以降、On<E>です。メソッドはevent()、event_mut()、observer()、original_event_target()、propagate(bool)です。
• **EntityEvent::set_target**にはuse bevy::ecs::entity::SetEntityEventTarget;が必要です。これはプレリュードに含まれていません。
• ストレージの選択は取り消せません。 コンポーネントにコンパイル時に組み込まれます。SparseSetは頻繁な挿入・削除向けに設計されています。Tableはデフォルトで、通常は反復がより高速です。ストレージを変更する前に、実際のワークロードをベンチマークしてください。
• #[require(T)]はT::default()を実行します。 T: !Defaultの場合は、#[require(T = expression)]または#[require(T = T::new(...))]を使用してください。
• 必須コンポーネントは再帰的に適用されます。 AがBを必要とし、BがCを必要とする場合、Aを挿入するとCも挿入されます。Aで直接指定したコンストラクターは、継承されたコンストラクターより優先されます。要件の循環は無効です。
• Replaceは0.19でDiscardに変更されました。 on_add、on_insert、on_discard、on_removeフックを使用してください。derive属性は#[component(on_discard = path)]です。
• フックはWorldの変更中に実行されるため、任意のSystemParamを受け取れず、フックが実行されているエンティティを破棄することもできません。柔軟性が必要な場合はオブザーバーを使用してください。
• Resourceは現在、Componentのサブトレイトです。 両方をderiveしないでください。各リソース値はリソースエンティティ上のコンポーネントとして保持され、同じリソース型の別の値を挿入すると、シングルトンを所有するエンティティが移動する場合があります。この動作が意図的でない限り、通常のエンティティコンポーネントとグローバルリソースには別々の型を使ってください。
• Bundleのderiveは引き続き使用できますが、多くの場合、「マーカー」コンポーネントに#[require(...)]を指定するほうが適しています。これにより、スポーン時のインターフェースを使いやすく保てます。

関連項目

• bevy-ecs-queries — コンポーネントの読み取り。
• bevy-ecs-systems — オブザーバーもシステムです。
• bevy-migration-0-17-to-0-18 — TriggerからOnへの変更、およびeventからmessageへの名称変更の一覧。
• bevy-migration-0-18-to-0-19 — Discardライフサイクルイベントと、リソースのコンポーネント化。