Skip to content

Kotlin 回呼參考 ​

伺服器會呼叫 plugin world 中的匯出。本頁介紹對應的 Kotlin 方法和註冊 API。有關主機匯入,請參閱介面對照表。

pumpkin.pluginClass 指定要實例化的無引數 PumpkinPlugin 子類。API 實現 PluginRootFunctions.Exports 和 Metadata。

生命週期和元資料 ​

WIT 匯出Kotlin 方法用途
init-plugin()open fun initPlugin(): Unit可選的啟動鉤子,由引導程式碼呼叫。
on-load(context)open fun onLoad(context: PluginContext): Result<Unit>註冊指令、事件或執行其他設定。預設返回成功。
on-unload(context)open fun onUnload(context: PluginContext): Result<Unit>可選的清理操作。橋接層還會關閉受管理的註冊和任務。預設返回成功。
metadata.get-metadata()abstract fun metadata(): PluginMetadata必需:返回名稱、版本、作者、描述、依賴項和權限。

PluginContext 是 pumpkin.Context.Context 的別名;PluginMetadata 是 pumpkin.Metadata.PluginMetadata 的別名。生命週期函式返回的 WIT result<_, string> 在 Kotlin 中表現為 Result<Unit>。

分發回呼 ​

以下是匯出橋接層的簽名。Server.Server 是伺服器資源。註冊 API 會分配處理器 ID;直接使用 WIT 時,則需要自行分配。

WIT 匯出 → Kotlin 重寫方法Kotlin 引數和返回值Kotlin 註冊 API
handle-event → handleEvent(eventId: UInt, server: Server.Server, event: Event.Event): Event.Eventevents.listen(...)
handle-command → handleCommand(commandId: UInt, sender: Command.CommandSender, server: Server.Server, args: Command.ConsumedArgs): Result<Int>commands.register(...)
handle-command-suggestion → handleCommandSuggestion(handlerId: UInt, sender: Command.CommandSender, server: Server.Server, request: Command.SuggestionRequest): Command.CommandSuggestionscommands.onSuggestions(...)
handle-task → handleTask(handlerId: UInt, server: Server.Server): Unittasks.afterTicks(...) 或 tasks.everyTicks(...)
handle-ipc-message → handleIpcMessage(sender: String, message: List<UByte>): Result<List<UByte>>ipc.onMessage(...)
handle-ai-goal-can-start → handleAiGoalCanStart(goalId: UInt, server: Server.Server, entity: World.Entity): BooleanaiGoals.register(...)
handle-ai-goal-should-continue → handleAiGoalShouldContinue(goalId: UInt, server: Server.Server, entity: World.Entity): Boolean同一個已註冊的 CustomAiGoal。
handle-ai-goal-start → handleAiGoalStart(goalId: UInt, server: Server.Server, entity: World.Entity): Unit同一個已註冊的 CustomAiGoal。
handle-ai-goal-tick → handleAiGoalTick(goalId: UInt, server: Server.Server, entity: World.Entity): Unit同一個已註冊的 CustomAiGoal。
handle-ai-goal-stop → handleAiGoalStop(goalId: UInt, server: Server.Server, entity: World.Entity): Unit同一個已註冊的 CustomAiGoal。
handle-generate-phase → handleGeneratePhase(generatorId: UInt, phase: World.GenerationPhase, chunk: World.ChunkBuffer): UnitchunkGenerators.set(...)

API 提供預設實現。僅在直接處理相應的 WIT 分發時,才需要重寫橋接方法。

低於 0x8000_0000u 的原始任務 ID 可供直接 WIT 處理器使用;任務輔助方法使用較高的範圍。此保留規則適用於任務回呼。受管理 API 的 ID 保留在 Kotlin 層內。

Kotlin 回呼層 ​

註冊方法接受以下回呼型別:

kotlin
// Kotlin API 回呼型別摘錄。
fun interface EventListener {
    fun onEvent(server: Server.Server, event: Event.Event): Event.Event
}

interface EventSubscription {
    fun unregister(): Boolean
}

fun interface CommandExecutor {
    fun execute(
        sender: Command.CommandSender,
        server: Server.Server,
        args: Command.ConsumedArgs,
    ): Result<Int>
}

fun interface SuggestionProvider {
    fun suggest(
        sender: Command.CommandSender,
        server: Server.Server,
        request: Command.SuggestionRequest,
    ): Command.CommandSuggestions
}

fun interface TaskAction {
    fun run(server: Server.Server)
}

fun interface IpcMessageHandler {
    fun onMessage(sender: String, message: List<UByte>): Result<List<UByte>>
}

interface CustomAiGoal {
    fun canStart(server: Server.Server, entity: World.Entity): Boolean
    fun shouldContinue(server: Server.Server, entity: World.Entity): Boolean
    fun start(server: Server.Server, entity: World.Entity)
    fun tick(server: Server.Server, entity: World.Entity)
    fun stop(server: Server.Server, entity: World.Entity)
}

fun interface ChunkGenerator {
    fun generate(phase: World.GenerationPhase, chunk: World.ChunkBuffer)
}

回呼使用生成的 WIT 型別。事件監聽器接收並返回 Event.Event;一個 CustomAiGoal 在同一個目標 ID 下實現五個回呼。

功能Kotlin 註冊WIT 操作API 行為
事件events.listen(context, type, priority, blocking) { server, event -> event } 返回 EventSubscriptioncontext.register-event-with-handle、context.unregister-event、handle-event分配 ID、分發事件、保留返回的事件,並在呼叫 unregister() 時移除主機註冊。
指令commands.register(context, command, permission) { sender, server, args -> Result.success(1) };commands.onSuggestions(node) { sender, server, request -> ... }command.execute-with-handler-id、command-node.suggest-with-handler-id、context.register-command、handle-command、handle-command-suggestion分配不同的執行和建議 ID,分發兩個回呼,並在卸載時釋放 Kotlin 處理器。
任務tasks.afterTicks(delayTicks) { server -> ... } 或 tasks.everyTicks(delayTicks, periodTicks) { server -> ... } 返回 ScheduledTaskscheduler.schedule-delayed-task、schedule-repeating-task、cancel-task、handle-task分配並回收處理器 ID、取消主機任務,並在卸載時清理。
傳入 IPCipc.onMessage { sender, message -> Result.success(response) }handle-ipc-message路由唯一的傳入訊息回呼。傳出的 Ipc.sendIpcMessage(...) 使用其生成的綁定。
自訂 AI 目標aiGoals.register(mob, priority, goal) 接受一個 CustomAiGoal 物件mob.add-custom-ai-goal 和五個 handle-ai-goal-* 匯出為五個回呼分配同一個目標 ID,並將它們分發到同一個 Kotlin 物件。
區塊生成chunkGenerators.set(world) { phase, chunk -> ... }world.set-chunk-generator 和 handle-generate-phase分配生成器 ID,並將各階段分發給 Kotlin 回呼。

物品欄、玩家、世界和文字操作可透過生成的綁定使用。

WIT 指令節點聲明瞭 require-with-handler-id,但插件 world 沒有匹配的條件檢查回呼匯出。指令權限使用 context.registerCommand(command, permission) 和伺服器的權限系統。

基於 MIT 授權條款釋出。