NEOLearn

Events and observers

Trigger events that run observer systems immediately, target events at entities, attach observers to entities, and bubble events up a hierarchy.

Updated October 20, 2026

On this page

An event is something that happens at a moment: a door opened, an enemy died, a button was clicked. When you trigger an event, every observer watching for it runs immediately, inside the trigger call, before anything else happens. Observers are systems, so they take the same parameters as any other system.

Use events and observers for one-off reactions. For streams of data that many systems process every frame, use messages.

A global event#

Rust
use neo::prelude::*;

#[derive(Event)]
struct LevelCompleted {
    time: f32,
}

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_observer(on_level_completed)
        .add_systems(Update, check_goal)
        .run();
}

fn on_level_completed(event: On<LevelCompleted>, mut commands: Commands) {
    info!("level done in {:.1} s", event.time);
    commands.spawn(Name::new("Fireworks"));
}

fn check_goal(mut commands: Commands, time: Res<Time>, goal: Query<(), With<GoalReached>>) {
    if !goal.is_empty() {
        commands.trigger(LevelCompleted { time: time.elapsed_secs() });
    }
}

#[derive(Component)]
struct GoalReached;
  • #[derive(Event)] makes a type an event.
  • app.add_observer(system) adds a global observer. Its first parameter is On<E>, which dereferences to the event.
  • commands.trigger(event) triggers it when commands apply. world.trigger(event) triggers it right away.

Entity events#

An EntityEvent targets one entity. Triggering it runs the global observers for that event and also the observers attached to that entity:

Rust
#[derive(EntityEvent)]
struct Explode {
    entity: Entity,
}

fn setup(mut commands: Commands) {
    commands
        .spawn((Name::new("Barrel"), Transform::default()))
        // runs only when Explode targets this barrel
        .observe(|event: On<Explode>, mut commands: Commands| {
            info!("boom");
            commands.entity(event.entity).despawn();
        });
}

fn detonate(mut commands: Commands, barrels: Query<Entity, With<Name>>) {
    for entity in &barrels {
        commands.trigger(Explode { entity });
    }
}

The target is the field named entity, the only field of a tuple struct like struct Explode(Entity);, or a field marked #[event_target].

observe on an entity spawns an observer entity that watches it. To share one observer across many entities, build it yourself:

Rust
let mut observer = Observer::new(on_explode);
for entity in barrels {
    observer.watch_entity(entity);
}
commands.spawn(observer);

Observers are entities with an Observer component. Despawning that entity removes the observer, and an entity-specific observer is despawned once every entity it watches is gone.

What the observer gets#

On On<E>What it is
*event / event.fieldThe event's data (On dereferences to E).
event.event_mut()Mutable access, so observers can change the event for the ones after them.
event.observer()The observer's own entity.
event.propagate(bool)Continue or stop bubbling (below).
event.original_event_target()For a bubbling event, the entity it was first triggered on.

Bubbling up a hierarchy#

An entity event can propagate from a child to its parent, then the grandparent, and so on, following ChildOf. This is how UI and picking events reach a button when you click its label.

Rust
#[derive(EntityEvent)]
#[entity_event(propagate, auto_propagate)]
struct Attack {
    entity: Entity,
    damage: u16,
}

#[derive(Component)]
struct Armor(u16);

fn block_attack(mut attack: On<Attack>, armor: Query<&Armor>) {
    let Ok(armor) = armor.get(attack.entity) else { return };
    if attack.damage <= armor.0 {
        attack.propagate(false); // fully blocked: stop here
    } else {
        attack.damage -= armor.0; // the rest goes on to the parent
    }
}
AttributeWhat it does
#[entity_event(propagate)]Allows propagation along ChildOf. Observers turn it on per event with propagate(true).
#[entity_event(propagate, auto_propagate)]Propagates by default; observers stop it with propagate(false).

As the event bubbles, attack.entity is the entity currently handling it.

Lifecycle events#

The engine triggers entity events when components are added and removed, so you can observe those too: On<Add<T>>, On<Insert<T>>, On<Discard<T>>, On<Remove<T>> and On<Despawn<T>>. See Hooks and lifecycle events.

Rust
app.add_observer(|add: On<Add<Enemy>>| {
    info!("enemy {} spawned", add.entity);
});

Run conditions and errors#

Observers can have run conditions like systems, and they can return Result:

Rust
app.add_observer(on_level_completed.run_if(in_state(GameState::Playing)));

Ordering and cost#

  • Observers of the same event run one after another, never in parallel, and in no guaranteed order. Don't rely on one observer running before another.
  • world.trigger runs observers immediately; commands.trigger runs them when commands apply. Commands that observers queue are applied after all the triggered observers have run.
  • Each event costs one call per matching observer. For thousands of values a frame, messages are cheaper.

Examples#

Run these from the engine core's workspace:

ExampleWhat it shows
cargo run --example observersGlobal and per-entity observers, lifecycle observers and observer run conditions.
cargo run --example observer_propagationAn attack bubbling from armour to the creature wearing it.
cargo run --example removal_detectionReacting to a component's removal with a Remove observer.

Next steps#