Nick Name Changer

NickNameChanger 0.0.18

NickNameChanger is a server mod for Hytale 0.6.x, built against Hytale Server 0.6.8. Its manifest requires server 0.6.8 or newer.

Set a nickname in chat, above your character, in the player list and on map player markers. Chat nicknames support colors, gradients, bold, italic and underline. Choose a separate color or gradient for your chat messages. Nameplates, the player list and map labels use plain text.

Your real username stays unchanged, so other plugins can still find you by your account name.

Report bugs on GitHub Issues. I don't read CurseForge comments.

The name at the top of the inventory or character screen comes from the game client and your account. No server mod can change it.

Install in your own world

1. Download the NickNameChanger 0.0.18 .jar from CurseForge.
2. Press Win+R.
3. Type %AppData%\Hytale\UserData\Mods and press Enter. If it is missing, open %AppData%\Hytale\UserData and create a folder named Mods.
4. Put the downloaded jar in Mods. Do not unpack it.
5. Start Hytale.
6. Open your world settings, go to Mods, then Global Mods, and enable NickNameChanger.
7. Enter the world and run /nnc in chat.

These are the default Windows paths. If you chose a custom Hytale data location, use its UserData\Mods folder instead.

For a dedicated server, put the jar in the server's mods folder and restart the server. No other mod is required for NNC's basic features.

Check that it loaded

Open %AppData%\Hytale\UserData\Logs after starting your world. Open the newest log and search for the exact prefix Integrations:. This line lists detected optional plugins and the selected chat route. Timestamps and logger names may appear before it. On a dedicated server, check its console or server logs.

Upgrade from 0.0.17 or older

Stop the world or server. Replace the old NickNameChanger jar with 0.0.18 and delete the old jar so only one version remains. Keep the mod's data folder.

Configuration migration runs automatically at startup. When old camelCase keys need conversion, the original is saved beside the config as config.json.pre-0.0.18.bak. Current keys use PascalCase. If both spellings exist, the PascalCase value wins; missing nested values are carried over.

Unreadable nickname data is not overwritten. A failed migration stops loading instead of replacing settings with defaults. Failed saves are reported. The update cannot recover data already deleted or overwritten; use an existing backup for that.

Commands

/nnc is the main command. /nick and /nickname are aliases. Use /nnc if another plugin owns either alias.

Use the editor for colors and gradients, or enter supported markup, for example /nnc <gradient:#FF5555:#5555FF>Steve</gradient>. Formatting requires nickname.format. Commands and the editor use the same nickname rules.

Permissions

With LuckPerms, unset nodes use these defaults. An explicit denial overrides the default. Message color and nickname formatting are separate permissions.

/lp user Steve permission set nickname.admin true

/lp group Admin permission set nickname.admin true

/lp group default permission set nickname.format false

/lp group default permission set nickname.msgcolor false

/lp user Steve permission set nickname.use false

Without LuckPerms, use Hytale's native permissions. The OP group's * includes nickname.admin. A native denial is -nickname.format or -nickname.msgcolor. Set permissions in your existing permissions.json. Keep its player assignments.

Optional mods and chat setup

Choose one plugin to format chat. NNC uses its own format when no other plugin does. ChatFormat controls NNC's own output.

If EssentialsPlus and EliteEssentials both format chat, messages can be sent twice. Disable chat formatting in one of them. NNC logs a warning. Do not enable several chat formatters just because they appear in this table.

PlaceholderAPI placeholders

The expansion identifier is nnc. Put tokens in a plugin's format where it supports HelpChat PlaceholderAPI and the corresponding color syntax.

The three chat nickname placeholders return the real name when Display.ShowInChat is off. Message-color tokens are empty without a saved color or permission. In a compatible MiniMessage format, put %nnc_msgcolor_open% before the message token and %nnc_msgcolor_close% after it. Keep that formatter's own message token.

Display settings and configuration

/nnc settings changes chat, nameplate and player-list display for all players. Saving applies the settings to online players and keeps them across restarts. Hiding nicknames does not delete them. Map display is separate: edit Display.ShowOnMap. It is off by default.

The server creates mods/NickNameChanger_NickNameChanger/config.json in its data directory. This is the running server's data folder, including the local server used by your world. The default ChatFormat is {prefix}<{username}>{suffix} {message}. Nicknames default to 2–32 visible characters. Cyrillic is enabled; unrestricted Unicode letters are disabled. Unique nicknames and real-name protection are enabled. The default banned words are admin, moderator, server and owner.

ChatFormat accepts {prefix}, {username}, {suffix} and {message}. Prefix and suffix come from LuckPerms when its integration and the corresponding switches are enabled. External %placeholders% require HelpChat PlaceholderAPI and their provider.

Nickname rules apply to visible text after supported formatting is parsed:

• MinLength and MaxLength exclude formatting tags.
• AllowedCharactersRegex must match the whole visible nickname. Examples: ^[A-Za-z0-9_]+$ or ^[A-Za-zА-Яа-яЁё0-9_]+$.
• An empty regex uses the built-in letters/digits rules plus spaces and _ - . ! ?. AllowCyrillic and AllowUnicode extend the allowed letters and digits.
• Literal < > & § % { } \ are forbidden in visible names. Supported color and gradient tags still work; they are parsed before these checks.
• BannedWords rejects any nickname containing a listed word, ignoring case.
• UniqueNicknames compares names without colors or case differences.
• BlockRealUsernames prevents using another known player's real name, including offline players. It knows names recorded by this server, not every Hytale account.
• Invalid rules stop nickname changes with an error. Invalid names are rejected with a reason, not silently shortened or rewritten.

Not working?

1. Check that NNC is enabled for this world and only one jar is installed.
2. Try /nnc, especially if another plugin has a /nick command.
3. Check the newest log for Integrations: and earlier loading errors.
4. Check permissions and Display settings. Map display is off by default.
5. Use one chat formatter. Changing NNC's ChatFormat does not change EP, EE or MCF's format.
6. Check the limits below. If it still fails, include server and plugin versions, relevant config and log errors in GitHub Issues. I don't read CurseForge comments.

Known limits

• The name at the top of the inventory or character screen is your account name from the game client. No server mod can change it.
• Nameplates, the player list and map labels show plain names, without chat gradients.
• EssentialsPlus's native nickname sync only accepts A-Z, a-z, 0-9 and _. Use its PlaceholderAPI route for other characters.
• HyperPerms 2.10.0 is not fully updated for server 0.6.8 (its player-list code throws an error). NNC cannot fix that part.
• A placeholder needs its provider and a formatter that understands its output. An adapter does not guarantee every third-party plugin version supports 0.6.8.