Skip to content

從 Bukkit 遷移事件 ​

在 Bukkit 中,事件透過建立實現 Listener 的類並使用 @EventHandler 註解方法來處理。

在 Pumpkin 中,事件處理器是透過 context.register_event_handler(...) 顯式註冊的結構或物件。Pumpkin 還區分阻塞和非阻塞事件,以最大限度提高伺服器併發性。


主要區別 ​

功能Bukkit / SpigotPumpkin
監聽器宣告方法上的 @EventHandler 註解實現 EventHandler<E> trait / 介面
註冊pm.registerEvents(listener, plugin)context.register_event_handler(handler, priority, is_blocking)
執行模型主執行緒執行(EventPriority)可選擇阻塞(順序執行/可取消)或非阻塞(併發執行)
取消event.setCancelled(true)對阻塞事件呼叫 event.cancel()

Pumpkin 中的阻塞與非阻塞事件 ​

Bukkit 的所有事件處理器都在伺服器主執行緒上順序執行,而 Pumpkin 允許你指定事件處理器是否為阻塞處理器:

rust
// Rust 中的註冊簽名:
context.register_event_handler(handler, priority, is_blocking)?;
  • 阻塞(is_blocking = true):按優先順序順序依次執行。可以修改事件資料(例如編輯加入訊息)或取消事件。
  • 非阻塞(is_blocking = false):在工作執行緒上併發執行。非常適合日誌記錄、指標收集或無需取消事件的外部通知。

程式碼對比:玩家加入事件 ​

1. Bukkit 實現(Java) ​

java
public class JoinListener implements Listener {
    @EventHandler(priority = EventPriority.NORMAL)
    public void onPlayerJoin(PlayerJoinEvent event) {
        Player player = event.getPlayer();
        event.setJoinMessage("Welcome " + player.getName() + " to the server!");
    }
}

// 在 JavaPlugin 中:
// getServer().getPluginManager().registerEvents(new JoinListener(), this);

2. Pumpkin 實現 ​

rust
use pumpkin_plugin_api::{
    Context, Plugin, PluginMetadata, Server,
    events::{EventData, EventHandler, EventPriority, PlayerJoinEvent},
    text::TextComponent,
};

struct JoinHandler;

impl EventHandler<PlayerJoinEvent> for JoinHandler {
    fn handle<'a>(
        &'a self,
        _server: Server,
        mut event: EventData<PlayerJoinEvent>,
    ) -> EventData<PlayerJoinEvent> {
        event.join_message = TextComponent::text("Welcome to the Pumpkin server!");
        event
    }
}

pub struct MyPlugin;

impl Plugin for MyPlugin {
    fn new() -> Self { MyPlugin }

    fn metadata(&self) -> PluginMetadata {
        PluginMetadata {
            name: "join_plugin".into(),
            version: "1.0.0".into(),
            authors: vec!["Developer".into()],
            description: "Join event handler".into(),
        }
    }

    fn on_load(&self, context: Context) -> pumpkin_plugin_api::Result<()> {
        // 註冊具有普通優先順序的阻塞事件處理器
        context.register_event_handler(JoinHandler, EventPriority::Normal, true)?;
        Ok(())
    }
}
python
from pumpkin_api import (
    Plugin, PluginMetadata, register_plugin,
    event, server, context
)

class MyPlugin(Plugin):
    def metadata(self) -> PluginMetadata:
        return PluginMetadata(name="join_plugin", version="1.0.0", authors=["Dev"], description="Join event")

    def on_load(self, ctx: context.Context) -> None:
        self.register_event(ctx, event.EventType.PLAYER_JOIN_EVENT, self.on_player_join)

    def on_player_join(self, srv: server.Server, evt: event.PlayerJoinEventData) -> event.PlayerJoinEventData:
        print(f"Player joined!")
        return evt

register_plugin(MyPlugin)

基於 MIT 授權條款釋出。