配置 | Suite

配置文件结构

Announcer 模块的配置由主配置文件 config.yml、公告条目目录 announcer/*.yml 和字幕组目录 subtitle/groups/*.yml 三部分组成。主配置文件控制 UI 注册、轮播节奏、跨服通道与字幕子设置；公告条目目录存放可轮播的公告定义；字幕组目录存放打字机字幕帧序列。

主配置（`config.yml`）

UI 配置节（`ui`）

统一管理公告 HUD 与字幕 HUD 的 UI ID 及注册行为。自配置版本 2 起，UI 相关配置从 settings 节迁移到 ui 节。

配置项	类型	默认值	说明
`ui.ui-id`	`string` / `list`	`AXS:announcer_hud`	公告 HUD 的 UI ID，支持字符串（单 UI）或列表（多 UI 同时发包）
`ui.subtitle-ui-id`	`string` / `list`	`AXS:subtitle_hud`	字幕 HUD 的 UI ID，支持字符串或列表
`ui.register-ui-on-enable`	`boolean`	`true`	启动/重载时是否自动注册 HUD（公告与字幕共用）
`ui.overwrite-ui-files`	`boolean`	`false`	是否强制覆盖 `plugins/ArcartX-Suite/ui/` 下的 HUD 文件（公告与字幕共用）

轮播设置节（`settings`）

配置项	类型	默认值	取值范围	说明
`settings.debug`	`boolean`	`false`	—	是否输出调试日志（发包内容、点击回包）
`settings.auto-play`	`boolean`	`true`	—	是否自动播放公告，`false` 时 HUD 同步配置但不主动滚动
`settings.check-interval-ticks`	`long`	`20`	`1` ~ `1200`	后台检查周期（tick，20 tick = 1 秒）
`settings.cooldown-ms`	`long`	`30000`	`0` ~ `3600000`	一整轮公告播完后的冷却时间（毫秒）
`settings.between-entry-interval-ms`	`long`	`30000`	`0` ~ `3600000`	同一轮中相邻条目切换间隔（毫秒）
`settings.text-width-font-size`	`int`	`60`	`1` ~ `200`	文本宽度估算字号，对应 HUD 中 `announcement_text` 的 `fontSize`
`settings.forward-to-qq`	`boolean`	`false`	—	是否将公告自动转发到 QQ 群（需 QQBot 模块）

check-interval-ticks、cooldown-ms、between-entry-interval-ms、text-width-font-size 均有服务端校验规则，超出范围会被自动钳制到合法区间。

公告条目目录（`entries-directory`）

配置项	类型	默认值	说明
`entries-directory`	`string`	`announcer`	公告条目目录路径，相对模块数据目录

目录下每个 .yml 或 .yaml 文件可包含多个条目，根键即为条目 ID。文件按名称升序加载，同一 ID 后定义的会覆盖先定义的。

跨服配置节（`cross-server`）

配置项	类型	默认值	说明
`cross-server.enabled`	`boolean`	`false`	是否启用跨服广播通道
`cross-server.redis.enabled`	`boolean`	继承宿主全局	是否走 Redis 后端，不填则继承宿主 `config.yml` 的全局配置
`cross-server.proxy.enabled`	`boolean`	继承宿主全局	是否走 Proxy Forward 后端，不填则继承宿主全局配置

跨服通道连接参数（Redis 地址、Proxy 配置、签名密钥等）由宿主 config.yml 的 cross-server 节统一管理，模块仅控制是否启用及后端覆盖。详见跨服配置指南。

字幕配置节（`subtitle.settings`）

配置项	类型	默认值	说明
`subtitle.settings.debug`	`boolean`	`false`	是否输出字幕调试日志（每帧 play 包与 close 包）
`subtitle.settings.groups-directory`	`string`	`subtitle/groups`	字幕组文件目录，相对模块数据目录
`subtitle.settings.show-background`	`boolean`	`true`	是否显示字幕底部背景板

字幕 HUD 的 UI ID 从统一 ui.subtitle-ui-id 读取，不再在 subtitle.settings 中单独配置。UI 注册/覆盖开关由 ui.register-ui-on-enable 与 ui.overwrite-ui-files 统一控制。

公告条目定义（`announcer/*.yml`）

每个公告条目文件根键为条目 ID，包含以下字段：

字段	类型	默认值	说明
`enabled`	`boolean`	`true`	是否启用该条目参与轮播
`text`	`string`	—	公告展示文本，支持 PlaceholderAPI 变量与颜色代码
`click-command`	`string`	—	点击公告时执行的命令，留空表示无点击事件；`<player>` 替换为点击者名

enabled: false 的条目不会下发到客户端，不参与轮播。text 为空的条目也会被过滤。

字幕帧定义（`subtitle/groups/*.yml`）

每个字幕组文件名（去掉 .yml）即为组 ID。文件内顶层数字节点按升序排列，每个节点为一帧字幕：

字段	类型	默认值	说明
`text`	`string`	—	字幕文本，支持颜色代码与 PlaceholderAPI 变量
`length`	`int`	`0`	打字机动画总字数，`0` 或负数时按可见文本长度自动计算
`time`	`int`	`1000`	打字机动画时长（毫秒）
`keep`	`double`	`1.0`	动画结束后停留时间（秒），最后一帧停留后自动关闭 HUD

字幕组文件还支持以下组级配置：

字段	类型	默认值	说明
`ui-id`	`string` / `list`	继承全局	指定本组使用的 UI ID，支持字符串或列表，不填则使用 `ui.subtitle-ui-id`

顶层节点必须是数字，系统按数字从小到大顺序播放。非数字节点会被跳过。

完整配置示例

主配置示例

config-version: 2
 
# 统一 UI 配置节
ui:
  # 公告 HUD UI ID（单 UI）
  ui-id: "AXS:announcer_hud"
  # 多 UI 示例（同一 payload 同时发给多个 HUD）：
  # ui-id:
  #   - "AXS:announcer_hud"
  #   - "AXS:announcer_hud_alt"
 
  # 字幕 HUD UI ID
  subtitle-ui-id: "AXS:subtitle_hud"
 
  # 启动/重载时自动注册 HUD
  register-ui-on-enable: true
 
  # 是否强制覆盖 UI 文件
  overwrite-ui-files: false
 
settings:
  debug: false
  auto-play: true
  check-interval-ticks: 20
  cooldown-ms: 30000
  between-entry-interval-ms: 30000
  text-width-font-size: 60
  forward-to-qq: false
 
# 公告条目目录（相对模块数据目录）
entries-directory: "announcer"
 
# 跨服广播（仅手动广播跨服，自动轮播不跨服）
cross-server:
  enabled: false
  # redis:
  #   enabled: true
  # proxy:
  #   enabled: true
 
# 字幕设置
subtitle:
  settings:
    debug: false
    groups-directory: "subtitle/groups"
    show-background: true

公告条目示例

# data/announcer/default.yml
# 目录下每个 *.yml 文件可包含多个条目，根键即为条目 ID。
 
# 欢迎公告条目
welcome:
  enabled: true
  text: "欢迎来到服务器，祝你游玩愉快。"
  click-command: ""
 
# 玩家个性化公告条目（PAPI 变量按接收玩家解析）
player:
  enabled: true
  text: "你好，%player_name%。"
  click-command: "say <player> 点击了公告"
 
# 禁用条目示例
disabled_entry:
  enabled: false
  text: "这条公告不会显示"
  click-command: ""

字幕组示例

# data/announcer/subtitle/groups/default.yml
# 顶层节点必须是数字，按从小到大顺序播放。
 
# 组级 UI 覆盖（可选）
# ui-id: "AXS:custom_subtitle_hud"
# 或多 UI：
# ui-id:
#   - "AXS:subtitle_hud_1"
#   - "AXS:subtitle_hud_2"
 
1:
  # 支持颜色代码和 PlaceholderAPI 变量
  text: "&f欢迎，%player_name%。"
  # 0 = 自动按可见文本长度计算
  length: 0
  # 打字机动画 1.4 秒
  time: 1400
  # 动画结束后停留 1 秒再切下一条
  keep: 1
 
2:
  text: "&e这是 AXS Subtitle 默认字幕组。"
  length: 0
  time: 1800
  # 最后一条会在 time + keep 后自动关闭 HUD
  keep: 1.5
 
3:
  text: "&b字幕支持多帧播放。"
  length: 0
  time: 1200
  keep: 0.8

配置版本迁移

模块支持配置版本自动迁移，当前配置版本为 2。

迁移	说明
1→2	UI 配置抽离到统一 `ui` 节：`settings.ui-id` → `ui.ui-id`，`subtitle.settings.ui-id` → `ui.subtitle-ui-id`，合并注册/覆盖开关到 `ui.register-ui-on-enable` 与 `ui.overwrite-ui-files`

模块启动时自动检测 config-version 并执行迁移，无需手动干预。迁移规则定义在 migrations/1-2.yml 中。

消息文件（`messages.yml`）

消息文件定义命令提示与状态文本，支持 & 颜色码和 {0} {1} 占位符。修改后执行 /axs reload announcer 生效。

消息键	说明
`prefix`	消息前缀
`common.unknown`	未知命令提示
`common.player-offline`	玩家不在线提示
`common.enabled` / `common.disabled`	启用/未启用文本
`help.*`	帮助命令各子命令说明
`status.*`	状态命令各行输出
`broadcast.*`	广播命令反馈消息
`subtitle.*`	字幕命令反馈消息

配置

本页目录