EssentialsX 聊天格式模块

EssentialsX Chat

> EssentialsX 的聊天格式模块，为主插件提供完整的聊天格式化能力：前缀、后缀、颜色、分组格式、聊天半径与喊话/提问系统。
基本信息

| 项目 | 信息 |
| --- | --- |
| 插件名称 | EssentialsX Chat |
| 所属套件 | EssentialsX（聊天模块） |
| 开发者 | mdcfe |
| 最新版本 | 2.22.0（发布于约 2 个月前） |
| 许可协议 | GPL-3.0-only |
| 兼容版本 | 1.8.7–1.8.9、1.9.4、1.10.2、1.11.2、1.12.2、1.13.2、1.14.4、1.15.2、1.16.5、1.17.1、1.18.2、1.19.4、1.20.6、1.21.11、26.1.2 等 |
| 运行平台 | Bukkit、Paper、Spigot |
| 运行环境 | Java 服务端（Minecraft Java 版） |
| 官方地址 | https://modrinth.com/plugin/essentialsx-chat-module |
简介

EssentialsX Chat 是 EssentialsX 的一个附加模块（addon），承接了主插件中绝大部分聊天格式化功能。它需要与对应版本的主模块 EssentialsX 搭配使用，单独放置无法工作 [citation:1]。

安装后，服务器可以为玩家自定义聊天中的前缀、后缀、颜色，并为不同的权限组设置完全不同的聊天格式——例如让管理员名字显示为红色、VIP 显示金色、普通玩家显示灰色。它是 EssentialsX 拆分模块化后，负责"聊天外观"的那一块。

为了避免与其他聊天插件冲突，如果没有安装 EssentialsX Chat 组件，EssentialsX 会自动停用大部分聊天格式处理 [citation:11]。安装本模块后，相关的 chat: 配置段才会真正生效 [citation:14]。
核心特性
全局与分组聊天格式

支持两种定义方式，可任选其一或组合使用 [citation:11][citation:14]：
全局统一格式：所有玩家共用一条 format 模板
按组分别格式：在 group-formats 下为不同权限组（如 default、admins）设置各自的格式，组名区分大小写，须与权限插件中的组名完全一致 [citation:14]

格式中可自由组合颜色代码（&9 天蓝、&7 灰色等）与占位符，也可以叠加粗体 &l、斜体等格式码 [citation:11]。
丰富的占位符

| 占位符 | 含义 |
| --- | --- |
| {DISPLAYNAME} | 显示名（含昵称与前缀） |
| {USERNAME} | 真实用户名（不含昵称与rank前缀） |
| {NICKNAME} | 昵称，无昵称则显示用户名 |
| {MESSAGE} | 玩家发送的消息内容 |
| {GROUP} | 玩家主组名称 |
| {PREFIX} | 权限插件提供的组前缀 |
| {SUFFIX} | 权限插件提供的组后缀 |
| {WORLD} | 世界别名 |
| {WORLDNAME} | 当前世界的完整名称 |
| {SHORTWORLDNAME} | 世界名的首字符 |
| {TEAMNAME} / {TEAMPREFIX} / {TEAMSUFFIX} | 计分板队伍名 / 前缀 / 后缀 |

[citation:7][citation:8]

> 注意：同时使用 {PREFIX}/{SUFFIX} 与 {DISPLAYNAME} 可能导致前缀/后缀重复显示，此时需取消注释 add-prefix-suffix 并设为 false [citation:14]。
聊天半径与喊话/提问
radius：玩家发言的传播半径（方块），设为 0 表示全局聊天 [citation:14]
拥有 essentials.chat.spy 的玩家可无视半径听到所有本地消息 [citation:14]
拥有 essentials.chat.shout 的玩家可用 ! 前缀发送全局喊话 [citation:14]
拥有 essentials.chat.question 的玩家可用 ? 前缀发送全服提问 [citation:14]
shout-default / persist-shout / question-enabled 控制喊话与提问的开关与持久化 [citation:10]
依赖 Vault + LuckPerms 提供前缀后缀

要真正显示分组前缀（如 [Admin]），需要：
Vault：用于桥接 EssentialsX 与权限插件，读取组前缀/后缀 [citation:7]
LuckPerms（或其他权限插件）：实际定义组、前缀、后缀 [citation:1]

EssentialsX Chat 本身不存储前缀，它从权限插件通过 Vault 获取 [citation:7]。
环境要求

| 项目 | 要求 |
| --- | --- |
| 服务端 | Bukkit / Spigot / Paper（推荐） |
| 主模块 | 必须安装版本匹配的 EssentialsX 主插件 |
| 依赖 | Vault、LuckPerms（或其他权限插件） |
| Minecraft 版本 | 1.8.7+，含 1.8.x – 1.21.11、26.1.2 等 |

> 仅支持 Java 版服务端，不适用于 Fabric / Forge / Bedrock。2.22.0 起需搭配同版本主模块，旧版本 EssentialsX 需使用对应版本的 Chat 模块。
安装方法
确认已安装版本匹配的 EssentialsX 主插件
安装 Vault 与 LuckPerms，并配置好权限组与前缀
将 EssentialsXChat-x.x.x.jar 放入 plugins/ 目录
启动或重启服务端，EssentialsX 会在 plugins/Essentials/config.yml 中生成 chat: 配置段
编辑 chat: 段后重载或重启生效
命令一览

EssentialsX Chat 模块本身没有专属命令——聊天格式完全通过配置文件定义，不在游戏内提供改格式的指令 [citation:8]。与之相关的命令来自主插件，主要用于昵称管理与聊天控制：

| 命令 | 说明 | 权限节点 |
| --- | --- | --- |
| /nick [玩家] <名字\|off> | 设置或清除自己/他人的昵称 | essentials.nick、essentials.nick.others |
| /nickname / /enick / /enickname | /nick 的别名 | 同上 |
| /essentials reload | 重载 EssentialsX 配置（含 chat 段） | essentials.reload |

[citation:6][citation:15]

命令示例板块已按需求省略。
配置说明

EssentialsX Chat 没有独立的 config.yml，其配置写在主插件的 plugins/Essentials/config.yml 底部的 chat: 段下 [citation:11]。配置项（文字说明，非完整字段清单）：
radius：聊天传播半径，0 为全局
format：全局聊天格式模板，默认 {DISPLAYNAME}: {MESSAGE}
group-formats：按组分别设置格式，去掉 # 注释后生效，组名大小写敏感
world-aliases：世界别名，可在格式中用 {WORLD} 替换世界名
shout-default / persist-shout / question-enabled：喊话与提问相关开关
add-prefix-suffix：是否自动追加前缀后缀，避免与 {DISPLAYNAME} 重复
use-paper-chat / modern-chat：1.16.5+ 是否使用 Paper 现代聊天事件（支持悬停/点击事件），冲突时可关闭，需重启生效

[citation:10][citation:14]

> 格式字符串须在引号内编辑，否则可能破坏解析；修改后需重启或重载生效 [citation:11]。
使用场景
RPG / 社区服：用前缀和颜色区分阵营、职业、身份
大型网络：不同权限组（默认、VIP、Mod、Admin）一目了然
多世界服务器：通过 {WORLDNAME} / 世界别名区分当前所在世界
强化管理：结合 chat.spy、shout、question 实现管理员监看与全服喊话
相关链接
Modrinth 项目页：https://modrinth.com/plugin/essentialsx-chat-module
EssentialsX 主插件：https://modrinth.com/plugin/essentialsx
官方聊天格式 Wiki：https://essentialsx.net/wiki/Chat_Formatting
颜色权限文档：https://essentialsx.net/wiki/color-permissions
模块拆分说明：https://essentialsx.net/wiki/Module-Breakdown
许可

本插件基于 GPL-3.0-only 许可发布，属 EssentialsX 项目的一部分，由 mdcfe 维护。