📥 安装与数据库

1. 创建 AdventureTops MySQL 数据库和专用账号。
2. 在需要采集或展示的 Paper 服务器安装插件。
3. 为每台服务器设置唯一 server.id 与角色。
4. 配置排名库及 AdventureLevel、AdventureBossRank 等外部源数据库。
5. 检查 /atops status，再执行首次 /atops recalc all。

storage:
  mysql:
    host: localhost
    port: 3306
    database: adventuretops
    username: playcraftdatauser
    password: "change-me"
    table-prefix: atops_
    pool-size: 8

🧩 集群角色

server:
  id: spawn
  role: display-and-aggregator

大型群组服可拆分角色，避免每个节点都重复聚合。所有节点通过 heartbeat 和可选 Redis 刷新版本保持一致。

🔌 数据源

部分来源直接读取其 MySQL，部分由集成监听器写入 AdventureTops 事件表。

📋 榜单定义

boards:
  在线时长排行榜_周榜:
    enabled: true
    source: adventureonline
    metric: online_seconds
    period: weekly
    limit: 10
    sort: DESC
    title: "在线时长排行榜 · 周榜"
    value-format: "{value_time}"

集成排行榜使用 integrated: true 和 boards 列表，将多个周期组合成 GUI/全息可切换组。

📅 周期与快照

周期按 cluster.timezone 计算，默认 Asia/Shanghai。展示读取已生成快照，不会在每次玩家打开 GUI 时实时扫描所有源库。

⚙️ 采集与聚合

collector:
  enabled: true
  flush-interval-seconds: 5
  max-flush-batch-size: 500
  online-sample-seconds: 60
aggregator:
  enabled: true
  snapshot-refresh-seconds: 300
  realtime-refresh-seconds: 30
sync:
  heartbeat-seconds: 30

• Collector 将高频事件缓存后每 5 秒最多批量写入 500 条。
• 普通快照默认每 300 秒刷新。
• 实时型刷新版本默认 30 秒。
• Redis 可选，用 adventuretops:refresh 频道通知其他节点刷新缓存。

🧰 排行榜 GUI

/tops 打开三级界面：

1. 首页：等级、Boss、抽奖、在线、通行证、好感度、签到、任务、种植、钓鱼、安全分等分类。
2. 分类页：选择某类下的排行榜组。
3. 榜单页：显示前十名头颅，并切换日/周/月/季/总榜。

关键槽位

🌟 全息榜单

hologram:
  enabled: true
  provider: TEXT_DISPLAY
  import-presets: true
  refresh-seconds: 30
  line-spacing: 0.28

holograms.yml 将 hologram ID 绑定到 board group 与世界坐标，例如：

holograms:
  在线时长排行榜:
    group: 在线时长排行榜
    location: "spawn,20,80,0,0,0"

组内可包含多个周期榜，展示服务按配置生成标题、名次与数值行。默认使用原生 TextDisplay，也声明了 DecentHolograms 软依赖。

🎁 排名奖励

rules:
  weekly_top3:
    enabled: false
    boards: ["*"]
    periods: [weekly]
    top: 3
    claim-key-mode: period
    commands:
      - "give {player} diamond {rank}"
      - "eco give {player} {value}"

防重复

每个玩家、名次、规则、榜单和周期的发放记录写入 MySQL；重复执行 recalc 不会重复奖励。

领取键

• period：每个自然周期一次。
• fixed-interval：按分钟间隔重新开放。
• 自定义 claim-key + active 时间窗：活动专用。

⌨️ 命令与权限

公开权限

• adventuretops.view：查看公共排行榜。
• adventuretops.gui.use：打开 GUI。
• adventuretops.click：点击全息交互。

⚙️ 配置参考

Redis

cluster:
  timezone: Asia/Shanghai
  storage: mysql
  redis:
    enabled: false
    host: localhost
    port: 6379
    password: ""
    channel: adventuretops:refresh

🧰 故障排查

榜单无数据

• 检查 board 的 source、metric 和 period 是否由对应集成提供。
• 验证源数据库连接和表权限。
• 执行 /atops recalc <榜单> 并查看返回行数。

多服展示不一致

• 所有节点连接同一 AdventureTops 数据库。
• 确保 timezone 一致。
• 检查 heartbeat，或启用 Redis refresh 通知。

全息不出现

• 世界已加载且坐标格式正确。
• hologram.enabled 为 true。
• 先用 holo create/refresh 测试单个 ID。

奖励重复或未发

检查规则 enabled、boards、periods、claim-key-mode、活动时间窗和数据库领取记录；不要手工删除记录后再执行 recalc。