联动 | Suite

Announcer 模块通过 Capability 注册、跨服通道、客户端变量推送等机制与其他模块和子系统联动。模块本身不使用 EventBus 发布事件，但通过 SubtitlePlayable 能力为其他模块提供字幕播放服务。

Capability 注册

模块在启动时注册以下 Capability，供其他模块通过 getCapability() 获取并调用：

AnnouncerBroadcastable（公开）

公告广播能力（@PublicCapability），外部插件经 AxsCapabilities.get(AnnouncerBroadcastable.class) 获取；Announcer 未启用时返回 null。文本支持 PlaceholderAPI 变量。

方法	说明
`broadcastNow(text)`	立即播报（打断当前展示），本服生效
`broadcastNow(text, forward)`	立即播报，`forward=true` 时跨服转发
`enqueue(text, forward)`	加入手动广播队列，当前展示结束后播报

SubtitlePlayable

提供字幕播放能力，接口定义位于 xuanmo.arcartxsuite.api.capability.SubtitlePlayable。由 Announcer 模块的 SubtitleService 实现，供 EventPacket、OnlineRewards、Conversation、QuestGps、AfkReward 等模块跨模块调用。

方法签名	返回值	说明
`playGroup(Player player, String groupId)`	`boolean`	为指定玩家播放字幕组，`true` 表示播放成功，`false` 表示字幕组不存在

使用示例（其他模块中）：

SubtitlePlayable subtitle = getCapability(SubtitlePlayable.class);
if (subtitle != null) {
    boolean ok = subtitle.playGroup(player, "welcome_subtitle");
    // true = 播放成功，false = 字幕组不存在
}

每个玩家同一时间只有一个字幕序列在播放。新的播放请求会终止旧序列（不发 close 包，新的 play 直接覆盖客户端状态）。

QQBotBroadcastable（消费方）

Announcer 模块作为消费方，通过 getCapability(QQBotBroadcastable.class) 获取 QQBot 模块提供的广播能力。当 settings.forward-to-qq 为 true 时，自动轮播与手动广播的公告文本会去除颜色代码后发送到所有已配置的 QQ 群。

方法签名	返回值	说明
`sendToGroup(long groupId, String message)`	`void`	向指定 QQ 群发送消息
`sendToAllGroups(String message)`	`void`	向所有已配置的 QQ 群发送消息

Announcer 调用的是 sendToAllGroups，消息格式为 [公告] <去除颜色代码的公告文本>。

跨服广播

跨服通道

模块通过 CrossServerAPI.openChannel("announcer", config, handler) 建立跨服通道。当 cross-server.enabled 为 true 且宿主已配置跨服连接时，手动广播命令（broadcast / broadcastnow / gbroadcast / gbroadcastnow）会转发到其他子服。

操作	转发方式	说明
`broadcast <文本>`	`gbroadcast` 时转发	排队广播，跨服时转发为排队消息
`broadcastnow <文本>`	`gbroadcastnow` 时转发	立即广播，跨服时转发为立即消息
`gbroadcast <文本>`	直接转发	跨服排队广播
`gbroadcastnow <文本>`	直接转发	跨服立即广播

自动轮播条目不会跨服转发，仅手动广播会跨服。

跨服消息行为

自身节点发送的消息自动跳过，消息按 ID 去重（不会重复播报）
immediate 类型立即打断当前展示广播，排队类型加入待播队列
公告文本在发送端渲染完成后传输，不含 PAPI 变量

跨服前提条件

宿主 config.yml 的 cross-server 节已正确配置（Redis 或 Proxy Forward）
cross-server.enabled 设为 true
可选覆盖后端：cross-server.redis.enabled / cross-server.proxy.enabled

跨服通道连接参数与签名密钥由宿主统一管理，模块仅控制启用开关与后端覆盖。详见跨服配置指南。

数据存储

Announcer 模块无数据库表。公告条目与字幕组从 YAML 文件加载（/axs reload announcer 重载），手动广播队列、字幕播放状态等运行时数据保存在内存中，重启后清空。

客户端变量推送

模块向 ArcartX 客户端推送以下变量：

变量名	类型	说明
`AXS_announcer_text`	`String`	当前公告文本（已渲染 PAPI）
`AXS_announcer_id`	`String`	当前公告条目 ID
`AXS_announcer_clickable`	`boolean`	当前公告是否可点击
`AXS_announcer_revision`	`String`	数据修订版本号（时间戳 + 自增序列）

这些变量与 display 包的字段同步推送，客户端 HUD 可通过任一渠道获取当前公告状态。

与其他模块联动

QQBot 模块

当 settings.forward-to-qq 为 true 且 QQBot 模块已启用时，Announcer 通过 QQBotBroadcastable.sendToAllGroups(message) 将公告转发到所有已配置的 QQ 群。转发前会去除 Minecraft 颜色代码，消息格式为 [公告] <纯文本>。

触发场景	转发条件	消息格式
自动轮播	`forward-to-qq: true`	`[公告] <公告文本>`
手动广播	`forward-to-qq: true`	`[公告] <广播文本>`

SubtitlePlayable 消费方

以下模块通过 SubtitlePlayable 能力调用 Announcer 的字幕播放功能：

模块	调用场景	说明
EventPacket	事件包触发字幕	事件条件满足时播放指定字幕组
OnlineRewards	全服签到目标达成	目标达成时向在线玩家播放字幕组
Conversation	对话剧情字幕	剧情动作中触发字幕播放
QuestGps	任务引导字幕	任务状态变更时播放字幕
AfkReward	AFK 奖励字幕	奖励触发时播放字幕

UI 自定义请参考图标指南与多 UI 指南。公告显示条件可参考条件指南。若需在自定义 HUD 中展示物品图标，可参考物品来源获取物品 JSON。

联动