ChatFormatMod

---

ChatFormatMod — 基于权限的聊天格式、昵称、标签和玩家档案

作为聊天模组的配套模组构建。 两者无缝协作 — ChatMod 处理物品显示、精灵图、悬停事件、广播和 MOTD；ChatFormatMod 负责聊天行布局、昵称、装饰标签、自定义头衔和玩家档案。所有 ChatMod 格式语法在每个格式字符串中都得到完全支持。

---

功能介绍

ChatFormatMod 让服务器管理员可以根据玩家的权限，完全控制每个玩家聊天消息的外观。管理员拥有不同于 VIP 的聊天风格，VIP 又不同于普通成员 — 所有内容都在简单的 YAML 中定义，无需重启。

在此基础上，玩家可以设置彩色昵称、选择显示在名字旁的装饰标签、填写个人档案，并拥有自定义头衔前缀和后缀 — 所有这些都绑定到一个权限驱动系统，开箱即用集成 LuckPerms。

---

特性

🎨 基于权限的聊天样式

在 formats.yml 中定义任意数量的聊天格式样式。玩家拥有的第一个权限节点对应的样式将被应用。空权限作为默认后备样式，匹配所有玩家。

styles:
  - id: admin
    permission: "chatmod.admin"
    format: "&c%custom_rank%&r &ö%displayname%&ö %tag% &7»&r %message%"

  - id: vip
    permission: "chatmod.vip"
    format: "&6[VIP]&r &ö%displayname%&ö %tag% &7»&r %message%"

  - id: default
    permission: ""
    format: "&ö%displayname%&ö %tag% &7»&r %message%"

每个格式字符串都支持完整的 ChatMod 令牌集 — 颜色代码、十六进制颜色、{悬停文本}、<action:…> 点击事件、[item]、[#SpriteName]、[@Name]、&= 换行、&+ 居中，以及所有 ChatMod 和 PlaceholderAPI 占位符。

---

🏷️ 昵称 /nickname /nick

玩家可以设置彩色显示昵称。权限精确控制允许的内容。

用法：

/nickname <昵称>               — 设置自己的昵称
/nickname reset                — 移除自己的昵称
/nickname <昵称> <玩家>        — 设置其他玩家的昵称（需要 .others 权限）
/nickname reset <玩家>         — 移除其他玩家的昵称（需要 .others 权限）

昵称不能为空。如果玩家尝试设置仅包含颜色代码而无可见文本的昵称，则会被拒绝。

重复保护： 两个 可见 文本相同（不区分大小写，去除所有代码）的昵称被视为重复。&1Testing 和 &aTesting 在纯文本 Testing 已被占用时都会被阻止 — 除非玩家持有 chatmod.nick.duplicate 权限，该权限允许已有名称的颜色变体共存。

权限	授予功能
chatmod.nick	使用 /nickname 命令
chatmod.nick.color	昵称中的颜色代码（&0–&f）
chatmod.nick.hexa	昵称中的十六进制颜色（&#RRGGBB）
chatmod.nick.format	昵称中的格式代码（&l、&o、&n 等）
chatmod.nick.length.<n>	最大可见字符长度 — 最高节点生效
chatmod.nick.length.unlimited	无长度限制
chatmod.nick.others	设置或重置其他玩家的昵称
chatmod.nick.bypass.taken	绕过所有昵称唯一性检查
chatmod.nick.duplicate	允许已占用可见名称的颜色变体

---

🔖 装饰标签 /tags

玩家打开一个 GUI 并选择一个装饰标签显示在名字旁。标签在 tags.yml 中定义，每个标签都有自己的权限节点。激活的标签作为 %tag% 插入到格式字符串中。

tags:
  - id: pvp
    permission: "chatmod.tag.pvp"
    display: "&c[PvP]&r"
    description: "准备战斗！"

---

🏅 自定义头衔

在 custom_ranks.yml 中定义头衔等级。玩家持有的第一个权限对应的头衔将被应用，并以三个占位符的形式暴露给格式字符串：

占位符	内容
%custom_rank%	前缀和后缀组合
%prefix%	仅头衔前缀
%suffix%	仅头衔后缀

---

👤 玩家档案 /profile

管理员在 profile_fields.yml 中定义任意数量的档案字段 — 性别、代词、国家、游戏风格或其他任何内容。玩家通过 GUI 填写。档案值通过 %profile:fieldId% 占位符出现在聊天中，并且在授予 chatmod.profile.view.others 权限时可供其他玩家查看。

字段支持预定义选项列表（左/右键循环）和自由文本输入（玩家在聊天中输入值）。

---

🔗 自动链接检测

聊天中输入的 URL 会自动转换为可点击的、美化格式的链接。完全可配置：

link_detection_enabled: true
link_shorten: true   # https://www.example.com/page → example.com/page
link_format: "&b&n%link%{请负责任地打开链接}"

{…} 悬停语法与 ChatMod 各处使用的相同 — 括号内的内容将显示为链接上的悬停文本。

---

🚪 自定义加入和离开消息

用自定义格式的消息替换原版的加入和离开消息。原版消息会被正确抑制，因此玩家永远不会看到重复显示。

joined_the_game: "&e%player% 加入了游戏"
joined_for_first_time: true
joined_for_first_time_format: "&e%player% 第一次加入了游戏！"
joined_after_name_change: "&e%player% 加入了游戏 &7(名字已更改)"
left_the_game: "&e%player% 离开了游戏"

新安装注意事项： 当模组安装在已有服务器上时，它会读取 Minecraft 自己的 usercache.json 来识别所有曾经加入过的玩家。这些玩家都被视为回归玩家 — 老玩家不会仅仅因为模组自己的数据文件尚未存在而看到“第一次加入”的消息。

---

聊天格式占位符

以下占位符可用于 formats.yml 格式字符串、加入/离开消息以及 ChatFormatMod 解析文本的任何位置：

占位符	值
%displayname%	昵称（如果已设置）或真实的 Minecraft 用户名
%player%	始终是真实的 Minecraft 用户名
%tag%	激活的装饰标签显示内容，或为空
%custom_rank%	头衔前缀 + 后缀合并
%prefix%	仅头衔前缀
%suffix%	仅头衔后缀
%message%	玩家的消息（格式字符串中必需）
%profile:fieldId%	档案字段的值，例如 %profile:gender%

所有 ChatMod 内置占位符（%online_players%、%date%、%time% 等）和 PlaceholderAPI 占位符也会自动解析。

---

📋 Tab列表及其他模组集成（PlaceholderAPI）

所有 ChatFormatMod 数据都以 PlaceholderAPI 占位符形式暴露，命名空间为 chatformatmod。任何支持 PlaceholderAPI 的模组 — Tab列表模组、记分板模组、名称标签模组 — 都可以直接获取昵称、头衔、标签和档案字段。

占位符	值
%chatformatmod:nick%	带有 § 颜色代码的昵称，或真实用户名
%chatformatmod:nick_plain%	去除所有颜色代码后的昵称
%chatformatmod:displayname%	nick 的别名
%chatformatmod:prefix%	头衔前缀，例如 §c§l管理员 §r
%chatformatmod:suffix%	头衔后缀
%chatformatmod:rank%	前缀 + 后缀组合
%chatformatmod:prefix_nick%	前缀 + 昵称
%chatformatmod:nick_suffix%	昵称 + 后缀
%chatformatmod:prefix_nick_suffix%	前缀 + 昵称 + 后缀全部组合
%chatformatmod:tag%	激活的装饰标签显示文本，或为空
%chatformatmod:style%	激活的格式样式 ID，例如 admin
%chatformatmod:profile:fieldId%	按 ID 获取任何档案字段的值
%chatformatmod:profile_gender%	gender 档案字段的简写
%chatformatmod:profile_country%	country 档案字段的简写

示例 — Tab列表模组中的玩家列表名称：

%chatformatmod:prefix_nick_suffix%

示例 — 名称标签模组（头顶前缀 / 名字 / 下方后缀）：

上方：  %chatformatmod:prefix%
名字：  %chatformatmod:nick%
下方：  %chatformatmod:suffix%  %chatformatmod:tag%

所有占位符中的颜色代码均以 § 前缀的旧格式代码返回，所有 Tab列表和名称标签模组都能理解。您无需自行转换 — 只需将占位符放入配置中即可生效。

需要安装 Placeholder API 才能在其他模组中解析这些占位符。当 PlaceholderAPI 存在时，它们会自动注册；如果不存在，ChatFormatMod 仍可正常运行于聊天格式化。

---

管理员命令

命令	描述	权限
/chatformat reload	重载所有 ChatFormatMod 配置	chatmod.admin.reload
/chatformat debug <玩家>	显示激活的样式、昵称、标签和头衔	chatmod.admin.debug
/nickname <昵称>	设置自己的昵称	chatmod.nick
/nickname reset	重置自己的昵称	chatmod.nick
/nickname <昵称> <玩家>	设置其他玩家的昵称	chatmod.nick.others
/nickname reset <玩家>	重置其他玩家的昵称	chatmod.nick.others
/tags	打开装饰标签选择 GUI	chatmod.tags
/profile	打开自己的档案 GUI	chatmod.profile
/profile <玩家>	查看其他玩家的档案	chatmod.profile.view.others

别名：/cf 用于 /chatformat，/nick 用于 /nickname。

---

配置文件

所有文件位于 config/chatformatmod/ 下。编辑后使用 /chatformat reload — 无需重启服务器。

文件	包含内容
chatformatmod.yml	全局开关、链接检测、加入/离开消息
formats.yml	基于权限的聊天格式样式
custom_ranks.yml	头衔前缀/后缀定义
tags.yml	装饰标签定义
profile_fields.yml	玩家档案字段定义
messages.yml	所有面向玩家的系统字符串

玩家数据（昵称、激活的标签、档案值）按世界存储在 <world>/chatformatmod_playerdata.json 中。

---

依赖项

模组	是否必需
Fabric API	✅ 必需
ChatMod	⭐ 强烈推荐
LuckPerms	✅ 基于权限的样式必需
Fabric Permissions API	✅ 必需
Placeholder API	🔶 可选 — 启用 PAPI 占位符和 Tab列表集成

ChatFormatMod 没有对 ChatMod 的硬编译时依赖 — 它可以独立运行，如果未安装 ChatMod，则会优雅降级（颜色代码降级为纯文本，无悬停/点击事件）。然而，这两个模组是作为一对设计的，一起使用效果最佳。

---

整合包政策

• ✅ 您 可以 在任何整合包中包含 ChatFormatMod。
• ❌ 整合包 不得出售。