GlobalChat（Velocity）

面向 Velocity 3.x 的全局聊天插件：多频道、MiniMessage 模板、子服白名单、冷却与 @ 提及、历史记录、管理员公告 /gb。

English: README_EN.md

---

功能概览

• 玩家通过 /g on [频道] 进入全局频道，消息按频道模板在允许的子服间广播。
• 频道可配置 allowed-servers、deliver-to-opted-out（未开 /g 的玩家是否仍收该频道消息）。
• 管理员 /gb 可按当前频道或指定频道发布公告，并可限制为仅当前子服。
• 可选聊天历史、@ 提及通知、冷却与权限绕过、进服自动开频道等。

---

环境要求

项目	版本
Java	17（maven.compiler.release=17）
Maven	3.6.3+（构建时校验）
代理端	Velocity 3.x（API 3.4.0）

运行时：发布 jar 仅内嵌 SnakeYAML（已重定位）；MiniMessage / Adventure 由 Velocity 提供，请使用与构建目标一致的 Velocity 版本。

---

安装

1. 将 globalchat-*.jar 放入 Velocity 的 plugins/ 目录。
2. 启动代理；插件在数据目录（@DataDirectory）生成 config.yml，并可放置 lang/<locale>.yml 覆盖文案（缺省回退内置语言包）。
3. 按需编辑 config.yml 后执行 /g reload（需权限），或重启代理。

控制台双行聊天日志：一行多为 Velocity 自带日志，另一行为插件 [GlobalChat] ...。可在 config.yml 将 chat.log-player-messages-to-console 设为 false 关闭插件侧额外日志。

---

配置（config.yml）

首次运行会从 jar 内 config.yml 复制到数据目录。以下为结构与要点；具体键名以生成文件为准。

语言

• language：如 zh_CN、en_US 等，对应 lang/zh_cn.yml、lang/en_us.yml（常见写法会自动规范化）。

频道（channels）

channels:
  default:
    format: "<reset>{reply_to}<gray>[{channel}]</gray> <dark_gray>[{server}]</dark_gray> <green>{player}</green><gray>:</gray> <white>{message}</white>"
    allowed-servers: []
    # deliver-to-opted-out: false

字段	说明
format	MiniMessage 模板，须含 {message}
allowed-servers	子服注册名白名单；[] 或不写 = 不限制
deliver-to-opted-out	是否向 未 开启全局聊天（/g off）的玩家投递该频道消息；已开在其它频道的玩家仍不会收到

白名单与发送：玩家已 /g on 某频道，但当前子服不在该频道 allowed-servers 内时，会提示 chat.server-not-allowed，且不会把消息落到后端普通聊天，避免误发。

频道 id 在配置中会被规范为小写。

聊天（chat）

常用项：max-message-length、message-prefix、cooldown-seconds、auto-on-join、历史相关键、mention-highlights、mention-ping-sound、log-player-messages-to-console、server-display-names（子服注册名 → {server} 显示名）。

@ 提及按 Java 版用户名规则解析（@ 后最多 16 位，字母数字下划线），仅匹配当前已连接本代理的玩家。

MiniPlaceholders（可选）

• 配置项 chat.mini-placeholders（默认 false）：为 true 时，在频道 format、admin-broadcast 模板及 message-prefix 中除内置 {player} 等以外，还可写 MiniPlaceholders 的 MiniMessage 标签。
• 需在代理安装插件 miniplaceholders（插件 id 与此一致）。本插件已声明为可选依赖，未安装时仍可正常运行，仅不会展开扩展标签。
• 解析上下文为发送方：全局聊天与历史回放为原消息发送玩家（若已离线则仅用全局占位、无 audience 上下文）；/gb 为执行命令的 CommandSource（玩家或控制台）。同一条聊天发往所有收件人时，展示内容一致（非按每位收件人单独解析）。

管理员公告（admin-broadcast）

admin-broadcast:
  format: "..."
  wrap-width: 48
  fullscreen:
    title: "..."
    subtitle: "..."
    fade-in: 10
    stay: 70
    fade-out: 20

wrap-width 用于公告正文自动换行（按 Unicode 码点计，0=关闭，默认 48）。
title / both 模式下可在模式后写非负整数秒覆盖大标题停留时间；chat 模式不会吞掉开头的数字。详见下文 [命令 → /gb](#管理员公告-gb)。

公告自动换行（wrap-width）说明与限制

• 插件会按 wrap-width 把正文切成多段，并通过 Adventure 在一条聊天/副标题组件内插入换行后再发送。
• 不保证在所有环境下都显示为多行：部分 客户端版本、资源包/字体、GUI 缩放、或其它 聊天/美化类插件（含后端）可能会把多行组件压成单行、截断或改变排版，看起来像「换行没生效」。
• 若你遇到换行无效，可依次排查：暂时关闭其它聊天相关插件对比；把 wrap-width 调到较小值（如 32）并用明显长于该宽度的正文测试；或拆成多次 /gb 发送短句。
• wrap-width 为 0 时不会自动断行，仅保留你在命令里输入的换行（一般难以输入，等同于依赖单次短公告）。

文案覆盖（messages，可选）

某项非空时优先于当前 lang/<locale>.yml：

• no-permission、toggle-on、toggle-off、usage、chat-cooldown、server-not-allowed

---

权限

节点	用途
globalchat.send.<channelId>	在对应频道发送全局消息
globalchat.command	/g 的管理子命令（list / on / off / history 等；info 不需要）
globalchat.reload	/g reload
globalchat.broadcast	/gb、/globalchatbroadcast（控制台不校验此节点）
globalchat.bypass.cooldown	绕过发送冷却
globalchat.* / globalchat.admin / *	视权限插件而定

---

命令

玩家与管理：/g

别名： /globalchat

/g <list|history|info|on|off|reload> [频道|页码]

/g info
/g reload
/g list
/g on [频道]
/g off
/g history [页码]

子命令	作用
/g on [频道]	开启频道；省略时为配置中第一个频道
/g off	关闭全局频道，恢复后端普通聊天
Tab 补全会按权限与已输入前缀过滤。

管理员公告：/gb

别名： /globalchatbroadcast
权限： globalchat.broadcast（玩家）；控制台不受此节点限制。

/gb [chat|title|both] [停留秒数] [--channel <频道>|--channel=<频道>] [-c <频道>] [--current-server|--local] <消息>

模式	效果
chat	仅聊天栏
title	仅大标题
both	聊天栏 + 大标题

默认投递

• 玩家：按发送者当前开启的频道筛选收件人（同频道 + deliver-to-opted-out 规则 + allowed-servers）。
• 控制台：默认频道 default（若无则回退配置第一个频道）。

可选参数

• --channel <id> / --channel=<id> / -c <id>：指定公告目标频道。
• --current-server / --local（或 local / current-server）：仅向发送者当前子服上的玩家投递（控制台使用时常无限服效果，因无“当前子服”）。

示例

/gb 维护公告
/gb --channel games 活动服公告
/gb both 8 --channel games --current-server 活动服即将重启

---

模板占位符

使用 Adventure MiniMessage 渲染。

频道消息（channels.<id>.format）

启用 chat.mini-placeholders 且安装 MiniPlaceholders 时，模板中还可使用各扩展提供的 MiniMessage 标签（与下表内置占位符可同时存在）。

占位符	含义
{reply_to}	回复前缀（当前保留占位，默认通常为空）
{player}	发送者名
{message}	正文
{server}	子服名（可走 chat.server-display-names）
{proxy}	固定 proxy
{channel}	频道 id
{ping}	延迟（ms）
{uuid}	UUID

公告（admin-broadcast.format / fullscreen.*）

占位符	含义
{player}	发送者（玩家名或 Console）
{message}	公告正文
{server}	发送者关联子服（含显示名映射）
{proxy}	代理标签
{channel}	本次公告的目标频道 id（不再固定为 broadcast）
{ping} / {uuid}	公告场景下为 —

---

1.19.1+ 签名聊天与 SignedVelocity

自 1.19.1 起聊天可带签名；在代理层不当拦截/改写可能导致断线（如 illegal protocol state）。

环境	行为
未装 SignedVelocity	为防踢，对 1.19.1+ 客户端不强拦转发，后端仍可能收到本地聊天 →可能出现「本地 + 全局」双条。
已装 SignedVelocity	可安全拦截转发，频道内通常只显示全局消息。

检测方式：插件 id signedvelocity（及名称/主类名含 signedvelocity）。官方要求代理与每个后端都安装对应组件；仅代理安装往往仍会出现双消息。详见 SignedVelocity README。启动时控制台会打印是否检测到 SignedVelocity；也可用 /velocity plugins 确认。

---

从源码构建

mvn package