Suite

命令与占位符

Lottery 命令、权限与 PlaceholderAPI 占位符

玩家命令

玩家命令通过 /lottery 触发（别名 /axslottery），由 LotteryPlayerCommand 处理。命令仅限玩家执行，控制台执行会提示 common.only-player。

命令参数说明
/lottery无显示帮助信息
/lottery help无显示帮助信息
/lottery open <奖池ID><奖池ID>打开指定奖池的抽奖 UI
/lottery info <奖池ID><奖池ID>打开奖池 UI 并自动跳转到详情页面
/lottery history <奖池ID><奖池ID>打开奖池 UI 并自动跳转到历史记录页面
/lottery claim无领取全部待发放奖励

玩家命令 Tab 补全

参数位置补全内容
第 1 参数help、open、info、history、claim（不依赖 service）
第 2 参数（open/info/history）全部已加载且启用的奖池 ID（依赖 service）

玩家命令权限

玩家命令无独立权限节点，所有在线玩家均可执行。命令通过 commandBindings() 绑定到 lottery 命令标签，由本体注册到 Bukkit。

管理员命令

管理员命令通过 /axs lottery 触发，由 LotteryAdminCommand 处理，实现 ModuleCommandHandler 接口。args[0] 为模块 ID（lottery），args[1] 开始为子命令。

命令参数说明
/axs lottery无显示帮助信息
/axs lottery help无显示帮助信息
/axs lottery status无查看全部已加载奖池的状态（ID、类型、显示名）
/axs lottery reset <玩家> <奖池ID><玩家> <奖池ID>重置指定玩家在指定奖池的抽奖状态（GACHA 重置保底计数，CASE 重置开箱次数）
/axs lottery give-points <玩家> <积分ID> <数量><玩家> <积分ID> <数量>向指定玩家发放积分
/axs lottery simulate <奖池ID> <次数><奖池ID> <次数>模拟指定奖池抽奖统计（不扣费、不发奖、不保存状态），次数范围 1-100000

管理员命令 Tab 补全

参数位置补全内容
args[1]（子命令）help、status、reset、give-points、simulate
args[2]（reset/give-points）在线玩家名
args[2]（simulate）全部已加载奖池 ID
args[3]（reset）全部已加载奖池 ID
args[3]（give-points）全部奖池中定义的积分点 ID

管理员命令权限

管理员命令通过 /axs 主命令分发，权限由本体的 ArcartXSuiteCommand 控制。模块通过 ModuleCommandHandler.commandId() 注册为 lottery，具备管理权限的发送者可执行全部子命令。

权限节点表

Lottery 模块的权限通过本体命令框架管控，无模块独立权限节点：

权限节点说明默认
arcartxsuite.admin执行 /axs 管理命令（含 /axs lottery）OP
arcartxsuite.command.lottery执行 /lottery 玩家命令所有玩家

玩家命令无独立权限校验，所有在线玩家均可执行 /lottery 系列命令。

PAPI 占位符

Lottery 模块通过 LotteryPlaceholderExpansion 注册 PlaceholderAPI 占位符，标识符为 axslottery。占位符格式为 %axslottery_<type>_<poolId>%。

占位符参数说明离线玩家
%axslottery_pity5_<poolId>%<poolId> 奖池 ID当前 5 星保底抽数需在线（离线返回 0）
%axslottery_pity4_<poolId>%<poolId> 奖池 ID当前 4 星保底抽数需在线（离线返回 0）
%axslottery_opens_<poolId>%<poolId> 奖池 IDCASE 奖池累计开箱次数需在线（离线返回 0）
%axslottery_guaranteed_<poolId>%<poolId> 奖池 ID下次 5 星是否大保底（必出 UP），返回 是/否需在线（离线返回 否）
%axslottery_fatepoints_<poolId>%<poolId> 奖池 ID当前命运点数（武器池定轨）需在线（离线返回 0）
%axslottery_point_<pointId>%<pointId> 积分 ID指定积分的余额支持离线（返回数值，异常返回 0）
%axslottery_points_<pointId>%<pointId> 积分 ID同上（points 别名）支持离线

占位符示例

%axslottery_pity5_character_event_1%      → 5 星保底抽数（如 42）
%axslottery_pity4_character_event_1%      → 4 星保底抽数（如 7）
%axslottery_guaranteed_character_event_1% → 是 / 否
%axslottery_fatepoints_weapon_event_1%    → 命运点数（如 1）
%axslottery_opens_default_weapon_case%    → 累计开箱次数（如 128）
%axslottery_point_stardust%               → 星尘积分余额（如 350）

guaranteed 占位符的 是/否 文本由 messages.yml 的 placeholder.guaranteed-yes / placeholder.guaranteed-no 定义。

UI Packet 触发

Lottery 模块通过 LotteryPacketHandler 处理客户端 UI 数据包。UI 通过 PacketBridgeAPI 与客户端通信，玩家操作 UI 时发送数据包到服务端，服务端处理后回推数据包更新界面。

数据包 ID

数据包 ID说明对应 UI
AXS_LOTTERY_GACHA祈愿（GACHA）数据包gacha-ui-id（默认 AXS:lottery_gacha）
AXS_LOTTERY_WISH祈愿全屏版（WISH）数据包wish-ui-id（默认 AXS:lottery_wish）
AXS_LOTTERY_CASE开箱（CASE）数据包case-ui-id（默认 AXS:lottery_case）

客户端动作（action）

客户端通过 data.get(0) 指定动作，服务端 LotteryPacketHandler.handle 分发：

action数据包参数说明
switch_poolGACHA / WISH / CASEdata[1] = 奖池索引切换当前选中奖池
pullGACHA / WISHdata[1] = 抽卡次数（1 或 10），data[2] = action_token执行抽卡
open_caseCASEdata[1] = action_token执行单次开箱
open_case_batchCASEdata[1] = 开箱次数（固定 10），data[2] = action_token执行十连开箱
historyGACHA / WISH / CASE无请求历史记录数据
detailsGACHA / WISH / CASE无请求奖池详情数据（概率、保底、条目）
exchangeGACHA / WISH无请求兑换商店数据
exchange_buyGACHA / WISHdata[1] = 商品 ID，data[2] = action_token执行兑换购买
refresh 或其他全部无刷新当前奖池界面

服务端回推数据包（sub-packet）

服务端通过 packetBridge.sendPacket 向客户端推送数据，subPacketId 标识数据类型：

subPacketId说明
update刷新奖池界面（奖池列表、消耗、保底、资源余额等）
result单抽结果（GACHA 或 CASE）
batch_result十连结果（GACHA 或 CASE）
history历史记录数据
details奖池详情数据（概率、保底、条目）
exchange兑换商店数据

Token 防抖机制

pull / open_case / open_case_batch / exchange_buy 动作需携带 action_token。服务端通过 checkToken 校验 token 并占用 inFlight 标记，防止并发重复请求。每次 update 推送时生成新 token，客户端需使用最新 token 发起操作。

CASE 开箱动画数据

单次开箱结果 result 包含 50 个伪随机物品填满动画带（animItemJson1 ~ animItemJson50），第 39 个（animWinnerSlot = 39）为中奖物品。十连开箱 batch_result 选最高稀有度的中奖物品作为动画停止位置展示。

UI 打开方式

触发方式说明
/lottery open <奖池ID>打开指定奖池 UI（GACHA 用 gacha-ui-id，CASE 用 case-ui-id）
/lottery info <奖池ID>打开 UI 并自动跳转详情页
/lottery history <奖池ID>打开 UI 并自动跳转历史页
手持 case-item 右键CASE 池专用，右键空气或方块时匹配手持物品，打开对应 CASE UI

相关文档

本页目录