Skip to content

快速入門 ​

可以使用 Zig 和 pumpkin-api-zig 綁定編寫 Pumpkin 插件。插件會編譯為 WebAssembly 元件,由伺服器從其 plugins 資料夾載入。

綁定從插件 API 生成,因此 API 提供的所有功能都可以在 Zig 中使用。此外,綁定還為幾乎每個插件都會執行的操作提供了輔助函數:監聽事件、宣告指令、構建文字、顯示選單、在聊天中提問、發放物品、排程工作、讀取設定檔案、儲存玩家資料以及進行網絡通訊。

這些指南涵蓋 pumpkin-api-zig 0.2.0。更新日誌列出了自 0.1.0 以來的更改。插件自己的 metadata.version 獨立於綁定版本。

前置要求 ​

你需要在 PATH 中安裝 Zig 0.16.0 和 wasm-tools。構建過程使用 wasm-tools 將插件 API 附加到你的程式碼,並將其打包為元件。

設定項目 ​

為插件建立一個目錄:

bash
mkdir my-zig-plugin
cd my-zig-plugin

將綁定新增為依賴:

bash
zig fetch --save git+https://github.com/Pumpkin-MC/pumpkin-api-zig#v0.2.0

發布頁面列出了每個已發布版本。若要更新,請使用新版本再次執行該指令。

然後建立 build.zig:

zig
const std = @import("std");
const pumpkin_api = @import("pumpkin_api_zig");

pub fn build(b: *std.Build) void {
    _ = pumpkin_api.addPlugin(b, b.dependency("pumpkin_api_zig", .{}), .{
        .name = "my-zig-plugin",
        .root_source_file = b.path("src/main.zig"),
    });
}

addPlugin 會針對 wasm32-wasi 編譯 src/main.zig,將 API 作為 pumpkin 模組提供給它,並將結果轉換為元件。

如果你在開發綁定本身,也可以改為依賴本地檢出的副本。路徑相對於你的項目:

zig
.dependencies = .{
    .pumpkin_api_zig = .{ .path = "../pumpkin-api-zig" },
},

編寫插件 ​

將以下內容放入 src/main.zig:

zig
const std = @import("std");
const pumpkin = @import("pumpkin");

pub const std_options: std.Options = .{ .logFn = pumpkin.logFn };

const MyPlugin = struct {
    pub const metadata: pumpkin.Metadata = .{
        .name = "my-zig-plugin",
        .version = "0.1.0",
        .authors = &.{"You"},
        .description = "An example plugin in Zig.",
    };

    pub const events = .{
        .player_join_event = onJoin,
    };

    pub fn onLoad(_: pumpkin.Context) !void {
        std.log.info("Hello from Zig!", .{});
    }

    fn onJoin(_: pumpkin.Server, ev: *pumpkin.EventData(.player_join_event)) void {
        std.log.info("{s} joined", .{ev.player.getName()});
    }
};

comptime {
    pumpkin.register(MyPlugin);
}

插件是傳給 pumpkin.register 的結構,後者會生成伺服器調用插件所需的一切。結構的宣告描述插件。只有 metadata 是必需的:它儲存伺服器顯示的名稱、版本、作者和描述,還可以列出對其他插件的 dependencies 以及插件需要的 permissions,後者在檔案與設定中介紹。events 列出要監聽的事件。onLoad 在插件的事件和指令註冊後執行,onUnload 在插件卸載前執行。

將 std_options.logFn 設定為 pumpkin.logFn 會把 std.log 輸出傳送到伺服器控制台;如果使用 std.log.scoped,輸出前還會帶上作用域。

API 提供的一切(包括事件的 player)都只存活到回調返回。句柄與記憶體介紹瞭如何延長其保留時間。

構建和執行 ​

bash
zig build
cp zig-out/my-zig-plugin.wasm /path/to/pumpkin/plugins/

啟動或重啟伺服器,日誌中應顯示插件的訊息:

text
[INFO] Hello from Zig!

WARNING

每個發布版本都會指明其構建所針對的插件 API 修訂。伺服器和插件需要相容的修訂;否則伺服器會拒絕插件並提示 Plugin was built against a different iteration of the API。更新任一方之前,請檢查你的發布版本對應的 WIT 提交。

範例 ​

綁定倉庫為 API 的每個部分都提供了一個小型插件。使用 zig build 構建倉庫會將它們全部構建到 zig-out/ 中。

範例展示內容
hello事件、指令和帶樣式的文字
heal使用 cmd.typed 讀取指令參數
menu帶按鈕和自由欄位的物品欄選單
prompt在聊天中回答的問題和可點選的選項
vault支援頁面選擇、使用情況指示和可設定容量的個人儲存
items構建、編輯和識別物品,以及給予和收取物品
tasks攜帶一個值的延遲任務和重複任務
config可重新載入的 TOML 設定檔案
store在獨立檔案中儲存每個玩家的資料
https使用 pumpkin.http 發起 Web 請求
tcp-server橋接聊天的 TCP 伺服器
udp接收和回覆 UDP 封包
dns查詢主機名的位址
http建立帶超時的 TCP 連線並發送純 HTTP 請求
nettest透過 /nettest 執行所有網絡路徑並報告各項結果

從 0.1.1 更新 ​

更改依賴後,使用 zig build 重新構建插件,並將新的 .wasm 複製到伺服器。替換可正常工作的安裝前,請確認其插件 API 修訂與伺服器匹配。

新輔助函數和選項在各自頁面中介紹:

方面0.2.0 中的用法
聊天提示問題、可點選選項、驗證、超時和自訂匹配。
選單free 欄位、現有 stacks、menu.items 和可設定的倉庫範例。
指令cmd.bad_argument 和 register_permission。
物品斜體樣式、顯式修飾符 ID、共享資料名稱空間和容量檢查。
設定格式選擇、檔案大小限制,以及檔案建立和重寫控制。
玩家資料編解碼器、鍵檢查、閒置驅逐和有界讀取。
網絡接收緩衝區大小和 HTTPS 證書包路徑。

基於 MIT 授權條款發布。