插件简介

QyRanking 是一款基于 PlaceholderAPI 变量的排行榜系统插件，支持多类排行榜、分组过滤、定期结算、分段奖励、DragonCore 动态界面展示。

前置依赖： QySQL、DragonCore、PlaceholderAPI

支持排行榜根据额外变量进行分类(例如职业区分)，奖励支持自动结算发放

---

指令

指令	权限	说明
/qyr help	qyranking.use	显示帮助
/qyr open [玩家]	qyranking.use	打开排行榜界面（指定玩家需 admin 权限）
/qyr reload	qyranking.admin	重载配置文件
/qyr settle <类型/all>	qyranking.admin	手动结算指定排行榜或全部
/qyr refresh	qyranking.admin	手动刷新排行榜数据
/qyr info <玩家>	qyranking.admin	查看玩家排行及奖励状态
/qyr testdata <类型/all> [数量]	qyranking.admin	生成测试数据（默认20条）

---

配置文件 (config.yml)

# 配置版本号，请勿修改
config-version: 1

# 是否开启调试模式（输出详细日志）
debug: false

# 全局排行榜更新间隔（秒），所有排行榜共用此周期刷新数据
global-update-interval: 300

# 排行榜类型配置
# 每个键名为排行榜的唯一ID，可自由添加多个
rankings:
  daily_kill:
    # 界面中显示的名称，支持颜色代码
    display-name: "&c每日击杀榜"

    # PlaceholderAPI 变量，作为排名依据的数值来源
    placeholder: "%statistic_kill%"

    # 排序方式: DESC(降序，值大排前) / ASC(升序，值小排前)
    sort-order: DESC

    # 结算周期: DAILY(每日) / WEEKLY(每周一) / MONTHLY(每月1号)
    settlement-cycle: DAILY

    # 结算时间点（HH:mm格式）
    # 例如 "05:00" 表示每天/每周一/每月1号的凌晨5点结算
    settlement-time: "05:00"

    # 结算后是否清零排行数据
    reset-after-settlement: true

    # 结算时对所有在线玩家执行的指令组（可选）
    # %player_name% 会替换为玩家名
    settlement-commands:
      - "papi set %player_name% statistic_kill 0"

    # 保留历史记录的期数（超出自动清理）
    history-save-count: 1

    # 缓存条目数量（总榜和各分组各缓存前 N 名，翻页范围也受此限制）
    display-count: 10

    # 分段奖励配置
    # 键名为名次或名次范围（如 "1", "2-3", "4-10"）
    # description: 奖励描述（支持多行，列表格式），显示在界面 $temp.reward_desc
    # empty-slots: 领取该奖励时要求的背包空槽位数量（0或不填则不检查）
    # commands: 领取时执行的指令组，%player_name% 替换为玩家名
    rewards:
      "1":
        description:
          - "&6&l冠军奖励"
          - "&7获得64颗钻石"
        empty-slots: 2
        commands:
          - "give %player_name% diamond 64"
      "2-3":
        description:
          - "&b亚军奖励"
          - "&7获得32颗钻石"
        empty-slots: 2
        commands:
          - "give %player_name% diamond 32"
      "4-10":
        description:
          - "&7参与奖励"
          - "&7获得16颗钻石"
        empty-slots: 1
        commands:
          - "give %player_name% diamond 16"

---

分组显示（可选）

在排行榜类型下添加 group-by 节点，可按变量值分组过滤显示。奖励仍按总榜发放。

  combat_power:
    display-name: "&b战力排行榜"
    placeholder: "%player_level%"
    sort-order: DESC
    settlement-cycle: WEEKLY
    settlement-time: "00:00"
    reset-after-settlement: false
    history-save-count: 1
    display-count: 10
    group-by:
      # 用于分组判断的 PAPI 变量
      placeholder: "%ss_job%"
      # 分组列表
      groups:
        swordsman:
          display-name: "&b剑士"
          match: "剑士"
        mage:
          display-name: "&d法师"
          match: "法师"
        archer:
          display-name: "&a弓手"
          match: "弓手"
    rewards:
      "1":
        description:
          - "&6&l冠军奖励"
        empty-slots: 2
        commands:
          - "give %player_name% diamond 64"

---

消息配置 (messages.yml)

所有玩家提示消息均可在 messages.yml 中自定义，支持 & 颜色代码和 %变量% 占位符。

---

DragonCore 界面

界面配置文件位于插件数据目录 graphical/qyranking.yml，首次启动自动生成。

发包协议

客户端通过 方法.发包('QyRanking', '操作', 参数...) 与服务端通信：

发包	参数	说明
type_buttons	无	生成所有排行榜类型切换按钮
group_buttons	类型ID	生成指定类型下的分组按钮
rank_items	类型ID, 分组ID, [页码], [每页数量]	生成排名条目 + 设置界面变量
switch_group	类型ID, 分组ID, [页码], [每页数量]	切换分组（刷新按钮+条目）
claim	类型ID	领取奖励
close	无	关闭界面回调

• 分组ID 传 'all' 表示总榜
• 页码/每页数量不传或 <=0 时不分页

动态组件 $temp 变量

type_btn（类型按钮）：

变量	说明
$temp.index	索引（从0开始）
$temp.type_id	排行榜类型ID
$temp.display	显示名称

group_btn（分组按钮）：

变量	说明
$temp.index	索引（从0开始）
$temp.group_id	分组ID（’all’=总榜）
$temp.display	显示名称

rank_item（排名条目）：

变量	说明
$temp.index	页内索引（从0开始）
$temp.rank	名次
$temp.player_name	玩家名
$temp.value	数值
$temp.uuid	玩家UUID
$temp.reward_desc	奖励描述（多行用换行分隔，无奖励时为空）

界面变量

---

核心机制说明

排行更新

• 每隔 global-update-interval 秒自动更新所有排行榜
• 获取在线玩家的 PAPI 变量值，合并离线缓存，排序后写入数据库
• 同分按先到达时间排序

结算流程

• 每分钟检查是否到达结算时间
• 结算时保存历史排名、生成待领取奖励、执行结算指令组
• 服务器重启时自动补结算（只补一次）

奖励领取

• 玩家在界面点击领取按钮
• 检查背包空槽位是否满足 empty-slots 要求
• 执行奖励指令组后标记已领取
• 每人每榜只存一期奖励，新结算覆盖旧奖励

离线处理

• 玩家下线时缓存当前变量值到数据库
• 下次更新周期合并离线缓存后清除
• 未上线玩家的奖励存数据库，上线后可在界面领取

---

权限节点

权限	默认	说明
qyranking.use	所有玩家	基础使用（打开界面、查看帮助）
qyranking.admin	OP	管理操作（重载、结算、刷新、查询）