bevy-ecs-components
Use when defining `#[derive(Component)]`, declaring required components with `#[require(...)]`, writing observers with `On<E>` or lifecycle observers with `On<Add<T>>` (NOT `On<Add, T>`), choosing Table versus SparseSet storage, or registering `on_add`/`on_insert`/`on_discard`/`on_remove` hooks in Bevy 0.20.
How do I install this agent skill?
npx skills add https://github.com/chrisgliddon/bevy-skills --skill bevy-ecs-componentsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides technical documentation and code examples for Bevy engine ECS components. No security risks were detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Bevy 0.20 — ECS Components
When to use this skill
- Defining a new
Componentfor game state. - Bundling components via
#[require(...)](the modern replacement for "bundles"). - Reacting to component lifecycle:
Add,Insert,Discard,Remove,Despawn. - Observers — reacting to entity-targeted events with
On<E>. - Choosing storage: Table (default, fast iteration) vs SparseSet (fast add/remove).
- Compiler errors mentioning
EventPatternorIntoObserverSystemafter an upgrade.
Canonical pattern
use bevy::ecs::lifecycle::HookContext;
use bevy::ecs::world::DeferredWorld;
use bevy::prelude::*;
// 1. Plain components.
#[derive(Component, Default)]
struct Health(f32);
#[derive(Component)]
struct Velocity(Vec3);
// 2. Required components: spawning `Player` auto-inserts the rest.
// Forms: `Type` (Default), `Type = expression`, `Type::ctor(...)`.
#[derive(Component)]
#[require(Health = Health(100.0), Velocity = Velocity(Vec3::ZERO), Transform)]
struct Player;
// 3. Sparse storage for tags added/removed every frame.
#[derive(Component)]
#[component(storage = "SparseSet")]
struct Stunned;
// 4. Lifecycle hook. `on_discard` is the 0.19+ name of `on_replace`.
#[derive(Component)]
#[component(on_discard = log_discard)]
struct Shield(u32);
fn log_discard(world: DeferredWorld, ctx: HookContext) {
let value = world.get::<Shield>(ctx.entity).map(|s| s.0);
info!("shield {value:?} on {:?} is being overwritten or removed", ctx.entity);
}
// 5. Entity-targeted event handled by observers.
#[derive(EntityEvent)]
struct Damage {
entity: Entity, // `entity` field or `#[event_target]` names the target.
amount: f32,
}
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_systems(Startup, spawn_player)
.add_systems(Update, deal_damage)
.add_observer(on_damage)
.add_observer(on_player_added)
.run();
}
fn spawn_player(mut commands: Commands) {
commands.spawn((Player, Shield(3), Name::new("hero")));
}
fn deal_damage(mut commands: Commands, query: Query<Entity, With<Player>>) {
for entity in &query {
commands.trigger(Damage { entity, amount: 10.0 });
}
}
// Observer param is `On<E>`.
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;
}
}
// Lifecycle observer. 0.20: the component lives inside the event type,
// `On<Add<Player>>`, not in a second generic `On<Add, Player>`.
fn on_player_added(add: On<Add<Player>>, names: Query<&Name>) {
let entity = add.event().entity;
info!("player {:?} spawned", names.get(entity).ok());
}
Lifecycle event cheat sheet
| Pattern | Fires when |
|---|---|
On<Add<T>> | T was added to an entity that did not have it. |
On<Insert<T>> | T was inserted (new or overwrite). |
On<Discard<T>> | T is about to be overwritten or removed (was Replace before 0.19). |
On<Remove<T>> | T is about to be removed. |
On<Despawn<T>> | An entity with T is about to be despawned. |
Add<(A, B)> is an OR filter: it fires when either component is added. On<Add<()>> plus Observer::with_component(id) watches dynamic components.
Gotchas (0.18 → 0.20)
- Observer
B: Bundlegeneric moved into the event (0.20).On<Add, A>→On<Add<A>>;On<Add>→On<Add<()>>.IntoObserverSystem<E, B, M, Out>becameIntoObserverSystem<E: EventPattern, M, Out>. An "inscrutable" error namingIntoObserverSystemusually means one generic too many. Theevent()of a lifecycle observer isAddEvent/InsertEvent/... with apub entityfield. Replace→Discard(0.19).on_replace→on_discard,#[component(on_replace = ..)]→#[component(on_discard = ..)],On<Replace, T>→On<Discard<T>>.Trigger<E>→On<E>(0.17). Methods:event(),event_mut(),trigger(),observer(),original_event_target(),propagate(bool).#[derive(Component, Resource)]on one type is an error (0.19).Resourceis now a subtrait ofComponent. Split the type into a component and a resource. AQuery<&T>whereT: Resourcematches the resource's hidden entity.- Lifecycle triggers gained fields (0.19).
EntityComponentsTriggernow also reports old/new archetypes. Destructure withEntityComponentsTrigger { components, .. }. Name: From<&'static str>only (0.20).Name::from(runtime_str)fails to compile; useName::new(s.to_owned()).ComponentIdconstants are typed (0.20).bevy::ecs::component::{ADD, INSERT, DISCARD, REMOVE, DESPAWN, IS_RESOURCE}areComponentId, notusize; call.index()for the number.ComponentInfo::id()is removed; keep theComponentIdyou looked it up with.#[component(summary_tick)](0.20) adds a per-column change tick soChanged<T>can skip whole tables. Mutations cost more; use it for rarely-changed, often-queried data.EntityEvent::set_event_targetrequiresuse bevy::ecs::event::SetEntityEventTarget;— not in the prelude.- Storage choice is irrevocable: it is compiled into the component. SparseSet adds/removes faster but iterates slower. Use Table (default) unless profiling says otherwise.
#[require(T)]runsT::default(). IfT: !Default, use#[require(T = expression)].- Hooks (
on_add,on_insert,on_discard,on_remove,on_despawn) arefn(DeferredWorld, HookContext). They run insideWorldmutations, cannot takeSystemParams, and cannot despawn their own entity. Prefer observers when you need flexibility. Ref<T>isClone + Copy(0.19). No need to re-fetch.Bundlederive still exists but#[require(...)]on a marker component keeps the spawn surface smaller.
See also
bevy-ecs-queries— reading components back out; broad queries andIsResource.bevy-ecs-systems— observers are systems;&mut Worldas aSystemParam.bevy-migration-0-18-to-0-19—Replace→Discard, resources-as-components.bevy-migration-0-19-to-0-20—On<Add<T>>,EventPattern, typedComponentId.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/chrisgliddon/bevy-skills/bevy-ecs-components">View bevy-ecs-components on skillZs</a>