Tab 模块跨服玩家列表聚合、聚合模式、退服宽限、批次节流与快照调试

跨服同步与聚合

付费模块

Tab 模块支持跨服玩家列表聚合：多个子服节点间互相同步 Tab 数据，玩家在任一子服都能看到全网络的在线列表。支持三种跨服模式：完整玩家列表合并、服务器聚合（每服一行）以及退服宽限（避免跨服跳传闪烁）。

跨服配置

配置层级

跨服功能涉及三个层级的配置：

配置层级	文件	字段	说明
宿主	`config.yml`	`cross-server` 节	Redis 或 Proxy 后端连接参数
模块	`config.yml`	`settings.cross-server`	全局默认开关
定义	Tab 定义文件	`cross-server`	单定义覆盖全局开关（不填时使用全局）

# ArcartXTab.yml
settings:
  server-id: "lobby-01"
  cross-server: true
  stale-snapshot-ms: 30000
  leave-grace-ms: 2000
  batch:
    window-ticks: 20
cross-server:
  enabled: true

Tab 定义中 cross-server 留空表示使用全局 settings.cross-server 默认值；显式设为 true 或 false 则覆盖全局设置。

server-id

server-id 是当前服务端节点的唯一标识，用于跨服数据中区分不同节点。每个节点必须配置唯一的 server-id。

settings:
  server-id: "survival-01"

server-id 为空时回退为 default。多节点部署时建议使用有意义的名称（如 lobby-01 / survival-01 / arena-01）。

跨服通道

跨服通道由宿主 config.yml 的 cross-server 节配置，支持两种后端：

后端	配置	说明
Redis	`redis.enabled: true`	通过 Redis Pub/Sub 广播消息，适合多机房部署
Proxy	`proxy.enabled: true`	通过 BungeeCord / Velocity Forward 转发消息，适合单代理网络

# 宿主 config.yml
cross-server:
  node-id: "survival-01"
  redis:
    enabled: true
    host: "127.0.0.1"
    port: 6379
    channel: "AXS:CROSS"
  proxy:
    enabled: false
    messenger-channel: "AXS_CROSS"

Redis 与 Proxy 可同时启用。两个后端均不可用时跨服功能静默禁用。

同步行为

每个刷新周期，本服对所有启用跨服的 Tab 定义广播本服玩家条目（含排序值、分组键与已渲染显示文本）
收到其他节点数据后合并排序显示；与本地节点相同 node-id 的数据被跳过
远程条目使用发送端预渲染的显示文本，各节点的 pack 显示格式由发送端决定——建议所有节点使用相同的 Tab 定义文件
远程条目不参与本地 filters 与 pinned top/bottom 规则（统一视为普通条目）
超过 stale-snapshot-ms（默认 30000，最小 5000）未更新的远程节点条目自动移除，节点崩溃时不会残留数据

聚合模式 aggregate

聚合模式将每个服务器（含本服与远程节点）在 Tab 中只占一行，不展开玩家列表。适用于大区网络的"服务器总览"视图。

配置

字段	类型	默认值	说明
`enabled`	`boolean`	`false`	是否启用聚合模式（仅 `cross-server: true` 时生效）
`line-pack`	`Object`	-	每行渲染模板，支持 `{server-id}` / `{server-display}` / `{server-online}` 占位符及完整 PAPI

line-pack 占位符

占位符	说明
`{server-id}`	服务端 ID（来自 `settings.server-id`）
`{server-display}`	服务端显示名（默认同 `server-id`）
`{server-online}`	当前服在线人数

# tabs/overview.yml
enabled: true
ui-targets:
  - ui-id: "AXS:tab"
    packet-handler: "tab"
cross-server: true
aggregate:
  enabled: true
  line-pack: "&b{server-display} &7- &f{server-online} 人在线"
pack: "{server-id}"

聚合模式下 PAPI 按本服第一个在线玩家上下文渲染；本服无在线玩家时占位符原样输出。line-pack 未配置时回退使用 pack 作为行模板。

退服宽限

退服宽限（leave-grace-ms）在玩家退服后保留其在跨服列表中的条目，避免跨服跳传时的"消失闪烁"。

配置项	默认值	说明
`leave-grace-ms`	`0`	退服宽限期（毫秒），0 表示禁用。典型值 1500~3000

settings:
  leave-grace-ms: 2000

宽限期内其他节点仍能看到该玩家，宽限期过后条目自动移除。

批次节流

batch.window-ticks 控制跨服广播的最小间隔，避免玩家进退服触发的额外刷新在短时间内产生广播风暴。

配置项	默认值	说明
`batch.window-ticks`	`0`	相邻两次广播最小间隔（ticks，50ms/tick）。0 表示禁用节流

settings:
  refresh-interval-ticks: 20
  batch:
    window-ticks: 20

建议将 batch.window-ticks 设为与 refresh-interval-ticks 相同的值，每个周期最多广播一次，同时不影响正常周期刷新。

调试快照

Tab 模块提供调试快照功能，用于存档 / 加载 / 复现跨服 Tab 状态。快照以 JSON 文件形式保存在 plugins/ArcartX-Suite/data/tab/snapshots/。

快照命令

命令	说明
`/axs tab snapshot save <name>`	保存当前快照到 JSON 文件
`/axs tab snapshot load <name>`	加载快照为虚拟节点
`/axs tab snapshot unload <name\|all>`	卸载虚拟节点
`/axs tab snapshot list`	列出已保存的快照与已注入的虚拟节点
`/axs tab snapshot delete <name>`	删除快照文件

快照名称仅允许字母 / 数字 / _ / -，长度 1~64。快照功能需要 axs.tab.debug 权限或 OP，仅限测试服使用。

跨服部署最佳实践

节点配置一致性

配置项	要求	说明
Tab 定义文件	所有节点一致	定义 ID、sort-keys、pack 必须相同，否则远程条目渲染异常
`server-id`	每节点唯一	用于区分不同节点
`cross-server`	所有节点启用	任一节点未启用则无法收发数据
`stale-snapshot-ms`	所有节点一致	避免不同节点的过期清理时间不同

性能建议

场景	建议
大型网络（10+ 节点）	使用聚合模式减少条目数量
高频 PVP 服	降低 `refresh-interval-ticks` 并启用 `batch.window-ticks` 节流
跨服跳传频繁	启用 `leave-grace-ms: 2000` 避免闪烁
调试跨服问题	使用 `/axs tab snapshot save` 存档现场

条件系统配置详见条件系统，图标配置详见图标配置。

跨服同步与聚合

本页目录