bevy_enum_event

Derive macros that generate Bevy event and message types from enum variants.

Overview

Transform enum variants into distinct Bevy event/message structs automatically. Each variant becomes a separate type in a snake_case module, eliminating boilerplate while preserving type safety.

use bevy::prelude::*;
use bevy_enum_event::EnumEvent;

#[derive(EnumEvent, Clone)]
enum GameEvent {
    Victory(String),
    ScoreChanged { team: u32, score: i32 },
    GameOver,
}

// Generates: game_event::Victory, game_event::ScoreChanged, game_event::GameOver

Bevy Compatibility

Installation

[dependencies]
bevy_enum_event = "0.3.2"

Macros

Bevy 0.17+ distinguishes between three event/message types:

• EnumEvent - Observer-based global events (triggered via world.trigger())
• EnumEntityEvent - Entity-targeted observer events with optional propagation
• EnumMessage - Buffered messages (written via MessageWriter, read via MessageReader)

EnumEvent

For observer-based events that are triggered globally and handled by observers.

use bevy_enum_event::EnumEvent;

#[derive(EnumEvent, Clone)]
enum PlayerState {
    Idle,                           // Unit variant
    Moving(f32),                    // Tuple variant
    Attacking { target: Entity },   // Named field variant
}

Using with Triggers and Observers

fn setup(mut app: App) {
    app.add_observer(on_attacking);
}

fn on_attacking(event: On<player_state::Attacking>) {
    println!("Attacking {:?}", event.target);
}

// Trigger the event
fn trigger_attack(mut commands: Commands) {
    commands.trigger(player_state::Attacking { target: Entity::PLACEHOLDER });
}

Deref Feature (default)

Single-field variants automatically implement Deref/DerefMut:

#[derive(EnumEvent, Clone)]
enum NetworkEvent {
    MessageReceived(String),  // Automatic deref to String
}

fn on_message(msg: On<network_event::MessageReceived>) {
    let content: &String = &**msg;
}

For multi-field variants, mark one field with #[enum_event(deref)]:

#[derive(EnumEvent, Clone)]
enum GameEvent {
    PlayerScored {
        #[enum_event(deref)]
        player: Entity,
        points: u32
    },
}

Disable with default-features = false.

EnumMessage

For buffered messages that are written/read between systems using MessageWriter/MessageReader. Important: Each message type must be registered with app.add_message::<T>().

use bevy::prelude::*;
use bevy_enum_event::EnumMessage;

#[derive(EnumMessage, Clone)]
enum NetworkCommand {
    Connect { address: String },
    Disconnect,
    SendData(Vec<u8>),
}

fn setup(app: &mut App) {
    // REQUIRED: Register message types
    app.add_message::<network_command::Connect>();
    app.add_message::<network_command::Disconnect>();
    app.add_message::<network_command::SendData>();
}

fn send_commands(mut writer: MessageWriter<network_command::Connect>) {
    writer.write(network_command::Connect {
        address: "127.0.0.1:8080".to_string(),
    });
}

fn receive_commands(mut reader: MessageReader<network_command::Connect>) {
    for cmd in reader.read() {
        println!("Connecting to {}", cmd.address);
    }
}

EnumEntityEvent

Entity-targeted events that trigger entity-specific observers.

Requirements

• Named fields only ({ field: Type } syntax)
• Must have entity: Entity field or #[enum_event(target)] on a custom field

use bevy::prelude::*;
use bevy_enum_event::EnumEntityEvent;

#[derive(EnumEntityEvent, Clone, Copy)]
enum PlayerEvent {
    Spawned { entity: Entity },
    Damaged { entity: Entity, amount: f32 },
}

// Entity-specific observer
fn setup(mut commands: Commands) {
    commands.spawn_empty().observe(|damaged: On<player_event::Damaged>| {
        println!("This player took {} damage", damaged.amount);
    });
}

Custom Target Field

#[derive(EnumEntityEvent, Clone, Copy)]
enum CombatEvent {
    Attack {
        #[enum_event(target)]
        attacker: Entity,
        defender: Entity,
    },
}

Event Propagation

Events can bubble up entity hierarchies:

// Basic propagation (uses ChildOf)
#[derive(EnumEntityEvent, Clone, Copy)]
#[enum_event(propagate)]
enum UiEvent {
    Click { entity: Entity },
}

// Auto propagation (always bubbles)
#[derive(EnumEntityEvent, Clone, Copy)]
#[enum_event(auto_propagate, propagate)]
enum SystemEvent {
    Update { entity: Entity },
}

// Custom relationship
#[derive(EnumEntityEvent, Clone, Copy)]
#[enum_event(propagate = &'static ::bevy::prelude::ChildOf)]
enum CustomEvent {
    Action { entity: Entity },
}

Control propagation in observers:

fn on_click(mut click: On<ui_event::Click>) {
    click.propagate(true);  // Continue bubbling
    let original = click.original_event_target();
}

Variant-Level Overrides

Override enum-level settings per variant:

#[derive(EnumEntityEvent, Clone, Copy)]
#[enum_event(propagate)]
enum MixedEvent {
    Normal { entity: Entity },  // Uses enum-level

    #[enum_event(auto_propagate, propagate)]
    AutoEvent { entity: Entity },  // Overrides with auto
}

Generics & Lifetimes

Full support for generic parameters and lifetimes:

#[derive(EnumEvent, Clone)]
enum GenericEvent<'a, T>
where
    T: Clone + 'a,
{
    Borrowed(&'a T),
    Owned(T),
    Done,
}

Choosing the Right Macro

License

MIT OR Apache-2.0