📋 AdventureTAB

一、简介

AdventureTAB —— 一款 Velocity 跨服 TabList 管理插件

AdventureTAB 让您轻松管理 Velocity 代理端的 Tab 列表显示。自动汇集所有子服务器在线玩家，按权限组排序，支持自定义 Header/Footer、CraftEngine 物品图标和表情符号，并提供极致性能的三级缓存机制。

AdventureTAB 支持 Velocity 3.4.0+ 代理端，并且会第一时间支持未来版本。

AdventureTAB

  • 跨服 TabList > 自动显示所有 Velocity 子服务器在线玩家
  • 权限排序 > 基于 LuckPerms 权限组权重自动排序
  • CraftEngine 物品图标 > 在玩家名旁显示手持自定义物品纹理
  • 表情符号 > CraftEngine 自定义表情嵌入显示名
  • 高性能缓存 > Caffeine 三级缓存 + 500ms 事件节流
  • MiniMessage > Header/Footer/显示名全面支持 MiniMessage + Legacy
  • 自定义 Header/Footer > 可配置多行 Tab 头部和底部文字
  • 服务器分组 > 按服务器分组显示玩家列表
  • 消息协议 > Velocity ↔ 子服通过 Plugin Message 实时同步

二、插件前置说明

都是非必须

  • LuckPerms — 权限组集成，用于排序和前缀
  • CraftEngine — 自定义物品图标和表情符号显示
下一篇安装部署 →

📥 安装部署

前置要求

组件版本必要性
Velocity3.4.0+必须
Java21+必须
LuckPerms5.4+可选
CraftEngine1.21+可选
Paper / Purpur1.21+后端服务器

安装步骤

  1. 将 AdventureTAB-1.0.0.jar 放入 Velocity 的 plugins/ 目录
  2. 启动 Velocity，插件自动生成 plugins/adventuretab/config.yml
  3. 编辑配置文件，按需启用 LuckPerms / CraftEngine 集成
  4. 执行 /atab reload 或重启 Velocity
上一篇← 功能概览
下一篇核心架构 →

🏗️ 核心架构

模块划分

模块类职责
主入口AdventureTabVelocity 插件生命周期、模块初始化、命令注册
配置管理ConfigManagerYAML 配置加载、默认值回滚、热重载
TabListTabListManagerHeader/Footer、跨服条目同步、显示名构建、排序
定时更新TabListUpdaterScheduledExecutorService 定期刷新
权限排序LuckPermsHookLuckPerms API 集成、权重解析、前缀后缀
CraftEngineCraftEngineHook插件消息接收、物品/纹理/表情数据处理
缓存CacheManagerCaffeine 三级缓存（权重/纹理/物品）
节流ThrottleManagerUUID 级别 ConcurrentHashMap 时间戳防抖
事件PlayerEventListenerServerConnected / Disconnect 事件处理
命令MainCommand/adventuretab (atab) 命令

数据流

ℹ️ 数据流向

后端服务器 (CraftEngine) → 插件消息 → Velocity (AdventureTAB) → TabList → 客户端

LuckPerms API → 权重/前缀 → CacheManager → 排序 → TabListEntry

上一篇← 安装部署
下一篇性能优化 →

⚡ 性能优化

缓存策略

缓存类型引擎过期时间最大容量说明
权限权重Caffeine10 分钟500减少 LuckPerms API 调用
纹理 Base64Caffeine1 小时200减少重复纹理传输
玩家物品模型Caffeine5 分钟500缓存当前手持物品信息

节流处理

对高频事件（如玩家切换服务器、物品装备变更）设置 500ms 节流间隔，使用 ConcurrentHashMap<UUID, Long> 记录每个玩家上次触发时间戳。

资源自动清理

  • Velocity 代理关闭时：清空所有缓存、注销事件监听器、关闭 ScheduledExecutorService 线程池
  • 玩家断开连接时：移除该玩家的权重缓存和物品缓存
  • 配置重载时：全部缓存失效，重新构建

异常处理

  • 所有 CraftEngine / LuckPerms API 调用包裹 try-catch，捕获异常时降级显示默认玩家名
  • 配置文件加载失败时自动使用内置默认配置，确保插件可启动
  • 通过 Velocity 的 Logger 输出分级日志
上一篇← 核心架构
下一篇LuckPerms →

🔑 LuckPerms 集成

排序原理

通过 LuckPermsProvider 获取玩家主权限组的 weight 元数据，权重值作为 TabList 的 listOrder 参数。权重越高的玩家排在 TabList 越靠前。

权重解析优先级

  1. 玩家 meta 中的 weight 键值
  2. 玩家主权限组 (primaryGroup) 的 group.weight
  3. 配置文件中的 luckperms.default-weight 默认值

动态更新

插件订阅 LuckPerms 的 UserDataRecalculateEvent，当玩家权限数据发生变化时自动更新缓存和 TabList 条目。

显示名占位符

占位符来源说明
{prefix}LP CachedMetaData玩家当前前缀
{suffix}LP CachedMetaData玩家当前后缀
{group}LP Group displayName主权限组显示名
上一篇← 性能优化
下一篇CraftEngine →

🎨 CraftEngine 集成

实现方式

由于 CraftEngine 运行在后端 Bukkit 服务器上，AdventureTAB 通过 Velocity 插件消息频道 (adventuretab:data) 接收后端服务器推送的数据。

功能说明

功能配置键说明
物品图标display-custom-item在玩家名旁显示手持自定义物品的纹理图标
表情符号emoji-support将聊天中使用的自定义表情同步到 TabList
纹理缓存max-texture-cache-size限制缓存的 Base64 纹理数量
⚠️ 注意

CraftEngine 集成需要在后端服务器安装配套的数据推送插件/模块，通过 adventuretab:data 频道向 Velocity 发送物品/纹理/表情数据。

上一篇← LuckPerms
下一篇消息协议 →

📡 插件消息协议

频道: adventuretab:data

类型ID名称数据格式方向
0x01物品更新[byte 0x01][long msb][long lsb][utf itemModel]后端 → Velocity
0x02纹理数据[byte 0x02][utf textureKey][utf base64Data]后端 → Velocity
0x03表情数据[byte 0x03][long msb][long lsb][utf emojiId]后端 → Velocity

字段说明

  • msb / lsb — 玩家 UUID 的 mostSignificantBits / leastSignificantBits
  • itemModel — CraftEngine item_model 纹理路径标识
  • textureKey — 纹理唯一键，与 itemModel 对应
  • base64Data — 纹理图片的 Base64 编码
  • emojiId — CraftEngine 自定义表情符号 ID
上一篇← CraftEngine
下一篇config.yml →

⚙️ config.yml

完整配置参考

# TabList 设置
tablist:
  header: "<gradient:gold:yellow>Adventure Network</gradient>"
  footer: "在线玩家: %velocity_total_players%"
  sort-by-permission-weight: true    # 按权限权重排序
  update-interval: 5                 # 定时更新间隔 (秒)
  name-format: "{prefix} {player}"   # 玩家名格式
  server-format: " &7[{server}]"     # 服务器后缀格式
  show-server-suffix: false          # 是否显示服务器后缀

# CraftEngine 集成
craftengine:
  enable-integration: true
  display-custom-item: true          # 显示手持物品图标
  emoji-support: true                # 表情符号支持
  max-texture-cache-size: 200        # 纹理缓存上限
  channel: "adventuretab:data"       # 插件消息频道

# LuckPerms 配置
luckperms:
  enable: true
  default-weight: 0                  # 默认权重
  cache-duration: 10                 # 权重缓存 (分钟)

# 性能配置
performance:
  throttle-ms: 500                   # 事件节流 (毫秒)
  texture-cache-duration: 60         # 纹理缓存 (分钟)

配置字段详解

字段类型默认说明
tablist.headerString渐变标题TabList 顶部文本，支持 MiniMessage
tablist.footerString在线人数TabList 底部文本
tablist.sort-by-permission-weightBooleantrue启用权限权重排序
tablist.update-intervalInteger5全局定时刷新间隔（秒）
tablist.name-formatString{prefix} {player}显示名格式
tablist.show-server-suffixBooleanfalse显示玩家所在服务器名
craftengine.enable-integrationBooleantrue启用 CraftEngine 集成
craftengine.channelStringadventuretab:data与后端通信的频道
luckperms.cache-durationInteger10权重缓存过期（分钟）
performance.throttle-msInteger500事件防抖间隔（毫秒）
performance.texture-cache-durationInteger60纹理缓存过期（分钟）
上一篇← 消息协议
下一篇占位符 →

📊 占位符

Header / Footer 占位符

占位符说明
%velocity_total_players%Velocity 全网在线玩家总数
%player_name%当前玩家名
%player_server%当前玩家所在服务器名

显示名格式占位符

占位符来源说明
{prefix}LuckPerms玩家前缀
{suffix}LuckPerms玩家后缀
{player}Velocity玩家名
{group}LuckPerms权限组显示名
{server}Velocity所在服务器名
上一篇← config.yml
下一篇命令 →

⌨️ 命令

命令别名权限说明
/adventuretab/atabadventuretab.use主命令，显示帮助
/atab reload-adventuretab.admin重载配置、刷新缓存、重建 TabList
/atab info-adventuretab.use查看运行状态
上一篇← 占位符
下一篇权限 →

🔐 权限

权限节点默认说明
adventuretab.useOP使用 /atab 命令
adventuretab.adminOP执行 reload 等管理操作
上一篇← 命令
下一篇更新日志 →

📝 更新日志

v1.0.0 2025-04-12

  • NEW 跨服 TabList — 基于 Velocity 3.4.0+ 的跨服 TabList 管理
  • NEW LuckPerms — 权限权重排序 + 前缀/后缀/组名显示
  • NEW CraftEngine — 物品图标 + 表情符号集成（插件消息协议）
  • NEW 缓存 & 节流 — Caffeine 三级缓存 + 500ms 事件节流
  • NEW MiniMessage — MiniMessage + Legacy 颜色码双重解析
  • NEW 热重载 — /atab reload 配置热重载
  • NEW 安全回滚 — 配置加载失败自动回滚至内置默认值
上一篇← 权限
© 2024-2026 Feiiy · AdventureTAB 跨服 TabList 管理 · QQ: 823959438