聊天提示
pumpkin.prompt 可以在聊天中向玩家提問,或顯示可點選的選項。插件決定哪些訊息算作答案、如何驗證答案以及問題何時結束。
提出問題
在 onLoad 中呼叫一次 prompt.listen(ctx, .{})。它會註冊聊天和離開事件,以及可點選選項使用的指令。
const pumpkin = @import("pumpkin");
const cmd = pumpkin.cmd;
const msg = pumpkin.msg;
const prompt = pumpkin.prompt;
const MyPlugin = struct {
pub const metadata: pumpkin.Metadata = .{
.name = "my-zig-plugin",
.version = "0.1.0",
};
pub const commands: []const cmd.Spec = &.{.{
.names = &.{"quantity"},
.permission = "my-zig-plugin:command.quantity",
.run = askQuantity,
}};
pub fn onLoad(ctx: pumpkin.Context) !void {
try prompt.listen(ctx, .{});
}
fn askQuantity(sender: cmd.Sender, _: pumpkin.Server, _: cmd.Args) cmd.Result {
const player = sender.asPlayer() orelse return cmd.fail("only players can answer");
prompt.ask(player, .{
.question = &.{.{ .text = "How many? Enter 1 to 64, or cancel.", .color = .aqua }},
.on_answer = gotQuantity,
.timeout = .seconds(30),
});
return cmd.ok(1);
}
fn gotQuantity(answer: prompt.Answer) prompt.Reply {
const amount = answer.number(u32) orelse 0;
if (amount < 1 or amount > 64) return prompt.retry(&.{.{ .text = "Enter a number from 1 to 64.", .color = .red }});
answer.player.sendSystemMessage(msg.fmt(.green, "You chose {d}.", .{amount}), false);
return prompt.done();
}
};
comptime {
pumpkin.register(MyPlugin);
}答案對應的聊天事件會被取消,因此不會廣播給其他玩家。Answer 包含 server、player、原始 text 和問題的 data。number(T) 讀取整數或浮點數,忽略兩端空格,無法讀取時返回 null。
顯示選項
choose 訊息可以按任意順序混合文字片段和選項。每個選項都有自己的標籤、處理函式和 data:
fn confirm(player: pumpkin.Player) void {
prompt.choose(player, .{
.message = &.{
.{ .text = .{ .text = "Continue? " } },
.{ .choice = .{
.label = &.{.{ .text = "[Continue]", .color = .green }},
.word = "continue",
.on_pick = confirmed,
} },
},
});
}
fn confirmed(_: pumpkin.Server, player: pumpkin.Player, _: usize) prompt.Reply {
player.sendSystemMessage(msg.plain("Confirmed."), false);
return prompt.done();
}標籤接受文字片段的樣式和懸停文字。點選行為由提示提供。word 還允許玩家鍵入選項,這是基岩版玩家所必需的,因為他們的聊天不支援可點選指令。不匹配任何選項的聊天訊息會繼續作為普通聊天處理。
在迴圈中建構的標籤需要有自己的後備陣列,並保持到 choose 返回。迴圈內臨時的 &.{ ... } 可能複用上一個標籤的記憶體。提示範例為其套件使用了獨立的標籤陣列。
結束或保留問題
答案和選項處理函式都返回 prompt.Reply:
prompt.done()結束問題。prompt.keep()讓問題保持開啟,包括其可點選選項。prompt.retry(spans)讓問題保持開啟併發送另一條訊息。
timeout 預設為 60 秒遊戲時間。keep() 和 retry() 保留原始截止時間,不會重新開始超時。將其設定為 null,可讓問題一直保持開啟,直到處理函式結束它或插件呼叫 prompt.cancel(player)。prompt.isAsking(player) 表示玩家是否有尚未結束的問題。
每個玩家同時只有一個問題。新問題會替換上一個問題,包括在答案處理函式中提出新問題的情況。舊的可點選選項攜帶舊問題的令牌,無法回答新問題。
問題在沒有完成答案的情況下結束時,會呼叫 on_end。它接收 (Server, Player, prompt.End, data),結束原因為 .timeout、.cancelled、.left 或 .replaced。處理函式以 done() 完成時不會執行它。
選擇行為
ask 接受一個 capture 回呼,其 Answer 與 on_answer 相同。返回 false 可讓訊息繼續作為普通聊天。預設捕獲所有訊息。除非更改,否則 cancel_word 為 "cancel";null 會將其關閉。系統會先檢查捕獲,因此如果過濾器對取消詞返回 false,該訊息也會作為聊天透過。
ask 和 choose 都接受 match 函式,用於比較聊天訊息和單詞。預設的 prompt.sameWord 會修剪兩端空格並忽略大小寫。原始 Answer.text 不會被更改。
傳給 listen 的選項可設定選項 command 及其 permission 和 description,以及 chat 事件的優先順序和阻塞模式。預設指令為 <plugin>-choose,權限為 <plugin>:command.choose。如果必須在答案廣播前將其取消,請讓聊天處理函式保持阻塞。
prompt.texts.not_a_player 和 prompt.texts.question_over 可以替換輔助函式自身的錯誤訊息。問題、選項、驗證和結束訊息均由插件提供。
會話資料和清理
Ask.data 會傳給答案和結束處理函式。Choose.data 用於 on_end;每個選項都有單獨的 data,會傳給 on_pick。它們是整數值,不是應用程式狀態的自有副本。對於多步驟表單,請將較大的狀態儲存在以玩家 UUID 為鍵的對映中,並將 data 用作索引或其他小型識別符號。
在答案成功時,以及 on_end 報告超時、取消、離開或替換時,都要移除該狀態。成功的 done() 不會呼叫 on_end。如果處理函式開啟下一個問題,請返回 done() 來結束舊問題;新會話會保持開啟。
輔助函式會複製選項詞和取消詞,供之後的回呼使用。問題和標籤片段會立即建構,因此棧上的陣列只需在 ask 或 choose 返回前保持有效。儲存在你自己的對映中的文字仍需要自有記憶體。