快速入门

本指南将帮助你开始使用 Zig 语言编写 Pumpkin 服务器插件。

针对 Pumpkin 的 Zig 语言插件通过官方提供的 pumpkin-api-zig 绑定编译为 WebAssembly（Wasm）组件。

---

前置要求

在构建 Zig 语言插件之前，请确保已安装以下工具：

• Zig：0.16.0 或更高版本。
• wasm-tools：确保已存在于系统的 PATH 环境变量中（构建脚本使用它来嵌入 WIT 元数据并生成 WebAssembly 组件）。

---

1. 初始化项目

为你的插件项目创建一个新目录：

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

获取并添加 pumpkin-api-zig 依赖：

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

在项目根目录下创建 build.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"),
    });
}

---

2. 编写插件代码

创建 src 目录并在 src/main.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 = &.{"你的名字"},
        .description = "Zig 语言编写的示例插件。",
    };

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

    pub fn onLoad(_: pumpkin.Context) !void {
        std.log.info("来自 Zig 插件的问候！", .{});
    }

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

comptime {
    pumpkin.register(MyPlugin);
}

关键要素：

• std_options：通过 pumpkin.logFn 将标准 Zig 日志（std.log）重定向到 Pumpkin 的日志系统。
• pub const metadata：定义组件加载时 Pumpkin 所需的插件元数据（名称、版本、作者、描述）。
• pub const events：定义插件注册的事件处理函数（例如 .player_join_event）。
• pub fn onLoad：Pumpkin 初始化插件时调用的入口点。
• pumpkin.register(MyPlugin)：在编译期生成所需的 WebAssembly 组件导出项与入口点。

NOTE

API 返回的所有对象（包括句柄）仅在当前回调执行期间有效。若需保留句柄，请调用 keep()，并在使用完毕后通过 deinit() 释放。

---

3. 构建插件

将插件编译为 WebAssembly 组件：

zig build

编译完成后，会在项目根目录生成 zig-out/my-zig-plugin.wasm 文件。

---

4. 运行插件

1. 将生成的 .wasm 文件复制到 Pumpkin 服务器的 plugins/ 目录中：

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

2. 启动或重启 Pumpkin 服务器：

   ./pumpkin

3. 查看控制台日志确认插件已成功加载：

   [INFO] 来自 Zig 插件的问候！