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

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

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

Display Settings (global, read-only)

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

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

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