bevy-ecs-components

Bevy 0.19 — ECS 组件

何时使用此技能

• 为游戏状态定义新的 Component。
• 通过 #[require(...)] 组合组件（这是“bundles”的现代替代方案）。
• 响应组件生命周期：生成、销毁、插入和移除。
• 使用观察者通过 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;——该项不在 prelude 中。
• 存储方式一经选择便无法更改：它会编译到组件中。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；派生属性为 #[component(on_discard = path)]。
• 钩子在 World 修改期间运行，不能接收任意 SystemParam，也不能销毁触发钩子的实体。需要更灵活的行为时，请使用观察者。
• Resource 现在是 Component 的子 trait。 不要同时派生两者。每个资源值都作为组件存储在一个资源实体上；插入另一个相同资源类型的值时，可能会改变哪个实体持有这个单例。除非有意采用这种行为，否则请将普通实体组件和全局资源定义为不同类型。
• Bundle 派生仍然可用，但大多数情况下，在“标记”组件上使用 #[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 生命周期事件和资源即组件。