Nick Name Changer

NickNameChanger

A server-side plugin for Hytale that allows players to customize their display nickname with colors, gradients, and text styles.

Features

• UI Editor — Graphical interface for nickname customization
  • 12 preset colors + custom color picker
  • 8 gradient presets + custom gradient colors
  • Text styles: Bold, Italic, Underline
  • Live preview
• Message Color — Per-player chat message coloring via UI tab or command
• Chat — Custom nickname displayed in chat messages
• Nameplate — Nickname shown above player's head
• Map — Custom name displayed on the world map (configurable)
• Tab List — Nickname visible in the player list
• Nickname Validation — Configurable rules: min/max length, banned words, Cyrillic support, unique nicknames
• Tag Injection Protection — Only safe markup tags are allowed (color, gradient, bold, italic, underline)
• Admin Settings GUI — Toggle nickname display globally with instant effect on all players
• Configuration — Control where nicknames appear via config.json or admin GUI
• LuckPerms — Prefix/suffix in chat with hex color support (<#RRGGBB>)
• EssentialsPlus Integration — Colored nicknames and message colors render through EP's chat formatter
• MiniChatFormatter Support — Compatible with MCF chat formatting
• Decorator Pattern — Preserves existing chat formatters from other plugins instead of overriding them
• Native Hytale API — Uses PluginManager for plugin detection, HytaleLogger, BuilderCodec for config
• API — Public API for other plugins to read player nicknames and display settings

Commands

Command	Description
/nick	Open the nickname editor UI
/nick <name>	Set a nickname via command
/nick reset	Reset to your original username
/nick msgcolor <hex>	Set chat message color (e.g. /nick msgcolor #FF5555)
/nick msgcolor gradient:#HEX1:#HEX2	Set message gradient color
/nick msgcolor reset	Reset message color to default
/nick settings	Open admin settings panel (requires nickname.admin)

Admin Settings Panel

The settings panel (/nick settings) gives administrators a GUI to control where nicknames appear globally.

• Three checkboxes: Show in Chat, Show on Nameplate, Show in Tab List / Map
• Changes apply instantly to all online players — no restart required
• Settings persist across server restarts
• Nicknames are never deleted — they are simply shown or hidden

Configuration

The plugin generates a config.json on first run:

{
  "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
    }
  }
}

Parameter	Description
chatFormat	Chat format with placeholders: {prefix}, {username}, {suffix}, {message}
display.showInChat	Show nicknames in chat messages
display.showOnNameplate	Show nicknames above players' heads
display.showInTabList	Show nicknames in the player list
display.showOnMap	Show nicknames on the world map (separate from tab list)
nicknames.minLength	Minimum nickname length (default: 2)
nicknames.maxLength	Maximum nickname length (default: 32)
nicknames.allowCyrillic	Allow Cyrillic characters in nicknames
nicknames.allowUnicode	Allow Unicode characters (emoji, CJK, etc.)
nicknames.uniqueNicknames	Prevent duplicate nicknames across players
nicknames.bannedWords	List of forbidden words (case-insensitive match)

Note: The display settings can also be changed through the admin GUI (/nick settings), which is the recommended way since it applies changes instantly to all online players.

Developer API

Other plugins can read nickname data and display settings via NicknameAPI. All methods are static and thread-safe.

Setup

Add to your manifest.json:

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

Check if loaded:

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

Nickname Methods

Method	Returns	Description
getNickname(UUID uuid)	String or null	Raw nickname with markup tags, or null if not set
getDisplayName(UUID uuid, String defaultName)	String (never null)	Nickname if set, otherwise defaultName
hasNickname(UUID uuid)	boolean	true if the player has a custom nickname
getOriginalUsername(UUID uuid)	String or null	Real username before nickname was set

Display Settings (global, read-only)

Method	Returns	Description
isShowInChat()	boolean	Are nicknames shown in chat? (default: true)
isShowOnNameplate()	boolean	Are nicknames shown above heads? (default: true)
isShowInTabList()	boolean	Are nicknames shown in player list? (default: true)

Usage Example

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!");
}

All methods return safe defaults if NickNameChanger is not loaded (null or false). getNickname() may contain markup tags — use getDisplayName() for a plain-text fallback.

For full API documentation with more examples, see GitHub README.

Installation

1. Download the latest JAR from GitHub Releases or from the Files tab above
2. Place it into Hytale\UserData\Mods
3. Launch the game and open world settings
4. Enable the mod in the Mods section
5. Load the world

Permissions

Permission	Description	Default
nickname.use	Access to /nick command	Allowed
nickname.format	Use colors, gradients, bold/italic/underline	Allowed
nickname.admin	Access to /nick settings (admin display panel)	Denied

nickname.use and nickname.format are allowed by default — works out of the box. To restrict, use the - prefix (e.g. -nickname.format).

nickname.admin is denied by default — only explicitly granted players/groups can access the settings panel.

For detailed LuckPerms examples and permissions.json setup, see GitHub.

Compatibility

Mod	Status
Standalone	Full support
LuckPerms	Full support: prefix/suffix in chat, hex colors, tab list sync
EssentialsPlus	Full support: colored nicknames + message color via EP chat
MiniChatFormatter	Compatible (MCF has known standalone issues)
Hyssential	Works as-is (picks up nickname automatically)
Essentials Core	Works as-is

NickNameChanger uses a decorator pattern for chat formatting — it preserves existing formatters from other plugins instead of overriding them. Plugin detection is done via native PluginManager API.

Limitations

• Inventory header — Cannot be changed (client-side rendered)

Localization

• English (en-US)
• Russian (ru-RU)
• Portuguese - Brazil (pt-BR)

Links

• GitHub — Source code, full documentation, API reference, changelog
• Issues — Bug reports and feature requests

Credits

• Author: Morgott