Event System & Cancellation

1. Registering Event Handlers

Register event listeners in on_enable() via context.register_event(...):

use potato_api::event::{PlayerJoinEvent, BlockBreakEvent, Cancellable};
use potato_api::text::Component;

// 1. Listen to player joins
context.register_event(|event: &mut PlayerJoinEvent| {
    let name = event.player.name();
    let comp = Component::from_mini_message(&format!("<yellow>Welcome, <gold>{}</gold>!</yellow>", name));
    event.player.send_component(&comp);
});

// 2. Prevent breaking bedrock
context.register_event(|event: &mut BlockBreakEvent| {
    if event.block.block_type == "minecraft:bedrock" {
        event.set_cancelled(true);
        if let Some(ref player) = event.player {
            player.send_message("§cBedrock is indestructible!");
        }
    }
});

2. Event Priorities

Event listeners execute in strict priority order. The earlier an event handler executes, the sooner it can inspect or cancel an event:

• 1. EventPriority::Lowest

  First to observe, useful for low-level modifications.

• 2. EventPriority::Low
• 3. EventPriority::Normal

  The default priority level.

• 4. EventPriority::High
• 5. EventPriority::Highest

  Runs right before action confirmation.

• 6. EventPriority::Monitor

  Read-only observation; actions MUST NOT be altered here.

3. The Cancellable Trait

Events that can be prevented implement the Cancellable trait:

pub trait Cancellable {
    fn is_cancelled(&self) -> bool;
    fn set_cancelled(&mut self, cancelled: bool);
}

Calling event.set_cancelled(true) instructs PotatoMC to abort the underlying action (e.g. block breaking, teleportation, player chat, inventory interaction).

4. Complete 26-Event Catalog