AdventureTAB Wiki

跨服 TabList - 自动显示所有 Velocity 子服务器在线玩家
权限排序 - 基于 LuckPerms 权限组权重自动排序
CraftEngine 物品图标 - 在玩家名旁显示手持自定义物品纹理
表情符号支持 - CraftEngine 自定义表情嵌入显示名
MiniMessage 格式 - Header/Footer/显示名全面支持 MiniMessage + Legacy 颜色码
Caffeine 高性能缓存 - 权限权重 10分钟、纹理 1小时过期
节流机制 - 500ms 高频事件防抖，避免 TabList 频繁刷新
配置回滚 - 配置文件加载失败时自动使用内置默认配置

模块划分

模块	类	职责
主入口	`AdventureTab`	Velocity 插件生命周期、模块初始化、命令注册
配置管理	`ConfigManager`	YAML 配置加载、默认值回滚、热重载
TabList 管理	`TabListManager`	Header/Footer、跨服条目同步、显示名构建、排序
定时更新	`TabListUpdater`	ScheduledExecutorService 定期刷新
权限排序	`LuckPermsHook`	LuckPerms API 集成、权重解析、前缀后缀
CraftEngine	`CraftEngineHook`	插件消息接收、物品/纹理/表情数据处理
缓存管理	`CacheManager`	Caffeine 三级缓存（权重/纹理/物品）
节流管理	`ThrottleManager`	UUID 级别 ConcurrentHashMap 时间戳防抖
事件监听	`PlayerEventListener`	ServerConnected / Disconnect 事件处理
命令	`MainCommand`	/adventuretab (atab) 命令

数据流

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

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

前置要求

组件	版本	必要性
Velocity	3.4.0+	必须
Java	21+	必须
LuckPerms	5.4+	可选
CraftEngine	1.21+	可选
Paper / Purpur	1.21+	后端服务器

安装步骤

将 AdventureTAB-1.0.0.jar 放入 Velocity 的 plugins/ 目录
启动 Velocity，插件自动生成 plugins/adventuretab/config.yml
编辑配置文件，按需启用 LuckPerms / CraftEngine 集成
执行 /atab reload 或重启 Velocity

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.header`	String	渐变标题	TabList 顶部文本，支持 MiniMessage
`tablist.footer`	String	在线人数	TabList 底部文本
`tablist.sort-by-permission-weight`	Boolean	true	启用权限权重排序
`tablist.update-interval`	Integer	5	全局定时刷新间隔（秒）
`tablist.name-format`	String	{prefix} {player}	显示名格式，支持 {prefix} {suffix} {player} {group}
`tablist.show-server-suffix`	Boolean	false	显示玩家所在服务器名
`craftengine.enable-integration`	Boolean	true	启用 CraftEngine 集成
`craftengine.channel`	String	adventuretab:data	与后端服务器通信的频道标识
`luckperms.cache-duration`	Integer	10	权限权重缓存过期时间（分钟）
`performance.throttle-ms`	Integer	500	高频事件防抖间隔（毫秒）
`performance.texture-cache-duration`	Integer	60	纹理 Base64 缓存过期（分钟）

命令	别名	权限	说明
`/adventuretab`	`/atab`	adventuretab.use	主命令，显示帮助
`/atab reload`	-	adventuretab.admin	重载配置、刷新缓存、重建 TabList
`/atab info`	-	adventuretab.use	查看运行状态（在线数、LP/CE 连接状态）

权限节点	默认	说明
`adventuretab.use`	OP	使用 /atab 命令
`adventuretab.admin`	OP	执行 reload 等管理操作

排序原理

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

权重解析优先级

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

动态更新

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

显示名占位符

占位符	来源	说明
`{prefix}`	LP CachedMetaData	玩家当前前缀
`{suffix}`	LP CachedMetaData	玩家当前后缀
`{group}`	LP Group displayName	主权限组显示名

实现方式

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

功能说明

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

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

频道: `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

Header / Footer 占位符

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

显示名格式占位符

占位符	来源	说明
`{prefix}`	LuckPerms	玩家前缀
`{suffix}`	LuckPerms	玩家后缀
`{player}`	Velocity	玩家名
`{group}`	LuckPerms	权限组显示名
`{server}`	Velocity	所在服务器名（需开启 show-server-suffix）

缓存策略

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

节流处理

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

资源自动清理

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

异常处理

所有 CraftEngine / LuckPerms API 调用包裹 try-catch，捕获异常时降级显示默认玩家名
配置文件加载失败时自动使用内置默认配置，确保插件可启动
通过 Velocity 的 Logger 输出分级日志，DEBUG 级记录权重计算和纹理转换过程

v1.0.0 (2025-04-12)

新增基于 Velocity 3.4.0+ 的跨服 TabList 管理
新增 LuckPerms 权限权重排序 + 前缀/后缀/组名显示
新增 CraftEngine 物品图标 + 表情符号集成（插件消息协议）
新增 Caffeine 三级缓存 + 500ms 事件节流
新增 MiniMessage + Legacy 颜色码双重解析
新增配置热重载 /atab reload
新增配置加载失败自动回滚至内置默认值

AdventureTAB

目录

1. 功能概览

2. 核心架构

模块划分

数据流

3. 安装部署

前置要求

安装步骤

4. 配置文件

config.yml

配置字段详解

5. 命令

6. 权限

7. LuckPerms 集成

排序原理

权重解析优先级

动态更新

显示名占位符

8. CraftEngine 集成

实现方式

功能说明

9. 插件消息协议

频道: `adventuretab:data`

字段说明

10. 占位符

Header / Footer 占位符

显示名格式占位符

11. 性能优化

缓存策略

节流处理

资源自动清理

异常处理

12. 更新日志

v1.0.0 (2025-04-12)

AdventureTAB

目录

1. 功能概览

2. 核心架构

模块划分

数据流

3. 安装部署

前置要求

安装步骤

4. 配置文件

config.yml

配置字段详解

5. 命令

6. 权限

7. LuckPerms 集成

排序原理

权重解析优先级

动态更新

显示名占位符

8. CraftEngine 集成

实现方式

功能说明

9. 插件消息协议

频道: adventuretab:data

字段说明

10. 占位符

Header / Footer 占位符

显示名格式占位符

11. 性能优化

缓存策略

节流处理

资源自动清理

异常处理

12. 更新日志

v1.0.0 (2025-04-12)

频道: `adventuretab:data`