命令与占位符

AfkReward 模块提供玩家命令与管理命令两套命令体系，并通过 PlaceholderAPI 向外暴露挂机状态占位符。HUD 界面通过 ArcartX Packet 通讯实时推送挂机数据到客户端。

玩家命令

玩家命令注册为 /afkreward 和 /afk 两个别名（另有 /axsafkreward、/axsafk 防冲突别名），功能完全相同。

玩家命令仅限玩家执行（控制台执行时提示"该命令只能由玩家执行"）。start 子命令支持 Tab 补全已启用且支持原地挂机的区域名。

status 命令输出

/afkreward status 显示以下信息：

list 命令输出

/afkreward list 显示所有在线挂机玩家，每行格式：

玩家名 | 区域: 区域名 | 模式: REGION/MANUAL | 时长: XX分XX秒

top 命令输出

/afkreward top 显示挂机时长排行榜（条目数由 manual.leaderboard-size 配置），每行格式：

No.1 玩家名 - 总时长: XX时XX分XX秒 - 总奖励: XX 次

排行榜数据合并内存中的在线玩家缓存与 DB 数据，按 total_seconds 降序排列。超过 60 秒未刷新时异步重新加载。

管理命令

管理命令通过本体统一命令 /axs afkreward <子命令> 调用。

status 管理命令输出

权限节点

档位匹配优先级：axs.afkreward.start.<areaId>.<tier> 优先于 axs.afkreward.start.<tier>。系统按配置顺序从高到低匹配，命中第一个有权限的档位即停止。无任何档位权限时默认取最后一个档位（通常是 common）。

PlaceholderAPI 占位符

模块注册 PlaceholderAPI 扩展，标识符为 axsafkreward。所有占位符以 %axsafkreward_<identifier>% 格式使用。

基础占位符

排行榜占位符

格式为 top_<排名>_<字段>，<排名> 从 1 开始，<字段> 可选 name / time / rewards。排名超出排行榜大小时返回空字符串。

区域统计占位符

<name> 为区域显示名。若区域名本身包含下划线，占位符解析会优先匹配 _today 和 _status 后缀。

全局统计占位符

HUD UI 包

模块内置 HUD 界面 afk_reward_hud.yml，在玩家进入挂机区域时自动显示。HUD 通过 ArcartX Packet 通讯实时更新数据，无需服务端菜单插件。

UI 配置

Packet 数据包

服务端每秒（20 tick）通过 PacketBridgeAPI.sendPacket() 向客户端推送 update 包，HUD 的 packetHandler 将包字段映射到 UI 变量：

packetHandler 脚本

HUD 配置了 init 和 update 两个包处理器，将 packet 字段绑定到 UI 变量：

packetHandler:
  init: |-
    var.area = packet['area']
    var.time = packet['time']
    var.next = packet['next']
    var.players = packet['players']
    var.session_rewards = packet['session_rewards']
    var.session_time = packet['session_time']
    var.visible = packet['visible']
  update: |-
    var.area = packet['area']
    var.time = packet['time']
    var.next = packet['next']
    var.players = packet['players']
    var.session_rewards = packet['session_rewards']
    var.session_time = packet['session_time']
    var.visible = packet['visible']

HUD 控件

HUD 面板包含一个背景面板和 6 个文本控件，所有控件可见性绑定到 var.visible 变量：

HUD 文件位于 data/afkreward/ui/afk_reward_hud.yml，可自由编辑布局与样式。设置 ui.overwrite-ui-files: false（默认）后模块不会覆盖你的修改。UI 编辑详见 图标配置 指南。

消息文件

消息文件位于 data/afkreward/messages.yml，支持 & 颜色码和 {0} {1} 占位符。修改后执行 /axs reload afkreward 即可生效。

消息分类

关键消息键