昵称修改器

NickNameChanger

一款服务端 Hytale 插件，允许玩家自定义显示昵称，支持颜色、渐变和文字样式。

功能特性

• UI 编辑器 — 昵称自定义的图形界面
  • 12 种预设颜色 + 自定义颜色选择器
  • 8 种渐变预设 + 自定义渐变颜色
  • 文字样式：粗体、斜体、下划线
  • 实时预览
• 消息颜色 — 通过 UI 标签或命令为每位玩家单独设置聊天消息颜色
• 聊天 — 在聊天消息中显示自定义昵称
• 头顶名牌 — 玩家头顶上方显示昵称
• 地图 — 在世界地图上显示自定义名称（可配置）
• Tab 列表 — 在玩家列表中显示昵称
• 昵称验证 — 可配置规则：最小/最大长度、禁用词、西里尔字母支持、唯一昵称
• 标签注入保护 — 只允许安全的标记标签（颜色、渐变、粗体、斜体、下划线）
• 管理员设置 GUI — 全局切换昵称显示，对所有玩家即时生效
• 配置 — 通过 config.json 或管理员 GUI 控制昵称显示位置
• LuckPerms — 聊天中的前缀/后缀，支持十六进制颜色 (<#RRGGBB>)
• EssentialsPlus 集成 — 彩色昵称和消息颜色可通过 EP 的聊天格式化器渲染
• MiniChatFormatter 支持 — 兼容 MCF 聊天格式
• 装饰器模式 — 保留来自其他插件的现有聊天格式化器，而非覆盖它们
• 原生 Hytale API — 使用 PluginManager 进行插件检测、HytaleLogger、BuilderCodec 进行配置
• API — 为其他插件提供公开 API，用于读取玩家昵称和显示设置

命令

命令	描述
/nick	打开昵称编辑器 UI
/nick <名称>	通过命令设置昵称
/nick reset	重置为原始用户名
/nick msgcolor <十六进制>	设置聊天消息颜色（例如 /nick msgcolor #FF5555）
/nick msgcolor gradient:#十六进制1:#十六进制2	设置消息渐变颜色
/nick msgcolor reset	将消息颜色重置为默认值
/nick settings	打开管理员设置面板（需要 nickname.admin 权限）

管理员设置面板

设置面板 (/nick settings) 为管理员提供了一个 GUI，用于全局控制昵称显示位置。

• 三个复选框：在聊天中显示、在头顶名牌显示、在 Tab 列表/地图显示
• 更改对所有在线玩家 即时生效 — 无需重启
• 设置跨服务器重启保持持久化
• 昵称永远不会被删除 — 仅显示或隐藏

配置

插件在首次运行时生成 config.json：

{
  "chatFormat": "{prefix}<{username}>{suffix} {message}",
  "display": {
    "showInChat": true,
    "showOnNameplate": true,
    "showInTabList": true,
    "showOnMap": false
  },
  "nicknames": {
    "minLength": 2,
    "maxLength": 32,
    "allowCyrillic": true,
    "allowUnicode": false,
    "uniqueNicknames": true,
    "bannedWords": ["admin", "moderator", "server", "owner"]
  },
  "integrations": {
    "luckperms": {
      "enabled": true,
      "showPrefix": true,
      "showSuffix": true
    }
  }
}

参数	描述
chatFormat	聊天格式，包含占位符：{prefix}、{username}、{suffix}、{message}
display.showInChat	在聊天消息中显示昵称
display.showOnNameplate	在玩家头顶上方显示昵称
display.showInTabList	在玩家列表中显示昵称
display.showOnMap	在世界地图上显示昵称（独立于 Tab 列表）
nicknames.minLength	昵称最小长度（默认：2）
nicknames.maxLength	昵称最大长度（默认：32）
nicknames.allowCyrillic	允许昵称中包含西里尔字母
nicknames.allowUnicode	允许昵称中包含 Unicode 字符（表情符号、中日韩文字等）
nicknames.uniqueNicknames	防止玩家间昵称重复
nicknames.bannedWords	禁词列表（不区分大小写匹配）

注意： display 设置也可以通过管理员 GUI (/nick settings) 更改，这是推荐的方式，因为它能对所有在线玩家即时应用更改。

开发者 API

其他插件可以通过 NicknameAPI 读取昵称数据和显示设置。所有方法均为 静态 且 线程安全。

设置

在您的 manifest.json 中添加：

{
  "OptionalDependencies": {
    "NickNameChanger:NickNameChanger": "*"
  }
}

检查是否已加载：

boolean hasNNC = PluginManager.get().getPlugin(
    new PluginIdentifier("NickNameChanger", "NickNameChanger")) != null;

昵称方法

方法	返回	描述
getNickname(UUID uuid)	String 或 null	带有标记标签的原始昵称，若未设置则返回 null
getDisplayName(UUID uuid, String defaultName)	String（不会为 null）	若已设置昵称则返回，否则返回 defaultName
hasNickname(UUID uuid)	boolean	若玩家拥有自定义昵称，则返回 true
getOriginalUsername(UUID uuid)	String 或 null	设置昵称前的真实用户名

显示设置（全局，只读）

方法	返回	描述
isShowInChat()	boolean	聊天中是否显示昵称？（默认：true）
isShowOnNameplate()	boolean	头顶是否显示昵称？（默认：true）
isShowInTabList()	boolean	玩家列表中是否显示昵称？（默认：true）

使用示例

import com.nickname.plugin.api.NicknameAPI;

UUID uuid = playerRef.getUuid();
String displayName = NicknameAPI.getDisplayName(uuid, playerRef.getUsername());
String original = NicknameAPI.getOriginalUsername(uuid);

if (original != null && !displayName.equals(original)) {
    broadcast(displayName + " (aka " + original + ") joined!");
}

如果 NickNameChanger 未加载，所有方法都会返回安全的默认值（null 或 false）。getNickname() 可能包含标记标签 —— 请使用 getDisplayName() 获取纯文本回退。

有关包含更多示例的完整 API 文档，请参阅 [GitHub README]。

安装

1. 从 GitHub Releases 或上方“文件”标签页下载最新 JAR 文件
2. 将其放入 Hytale\UserData\Mods
3. 启动游戏并打开世界设置
4. 在模组部分启用该模组
5. 加载世界

权限

权限	描述	默认值
nickname.use	访问 /nick 命令	允许
nickname.format	使用颜色、渐变、粗体/斜体/下划线	允许
nickname.admin	访问 /nick settings（管理员显示面板）	拒绝

nickname.use 和 nickname.format 默认允许 —— 开箱即用。如需限制，请使用 - 前缀（例如 -nickname.format）。

nickname.admin 默认拒绝 —— 只有被明确授予权限的玩家/组才能访问设置面板。

有关 LuckPerms 的详细示例和 permissions.json 设置，请参阅 GitHub。

兼容性

模组	状态
独立模式	完全支持
LuckPerms	完全支持：聊天中的前缀/后缀、十六进制颜色、Tab 列表同步
EssentialsPlus	完全支持：通过 EP 聊天的彩色昵称 + 消息颜色
MiniChatFormatter	兼容（MCF 已知存在独立问题）
Hyssential	开箱即用（自动拾取昵称）
Essentials Core	开箱即用

NickNameChanger 在聊天格式化中使用 装饰器模式 —— 它保留来自其他插件的现有格式化器，而非覆盖它们。插件检测通过原生 PluginManager API 完成。

局限性

• 背包标题 —— 无法更改（由客户端渲染）

本地化

• 英语 (en-US)
• 俄语 (ru-RU)
• 葡萄牙语 - 巴西 (pt-BR)

链接

• GitHub — 源代码、完整文档、API 参考、更新日志
• 问题反馈 — 错误报告和功能请求

致谢

• 作者： Morgott