CustomNick

CustomNick – Player Nickname Plugin for Paper 1.21.x
CustomNick is a lightweight and fully-featured Paper plugin that allows players to change their visible nickname with full support for Legacy colors, Hex codes, and MiniMessage formatting.

It works seamlessly in chat, tab-list, and display names, with persistent storage and integration with PlaceholderAPI.

✨ Features

• Change nicknames in chat, tablist, and display name
• Persistence of nicknames in nicks.yml (UUID → nick)
• Support for three color formats: Legacy, Hex, MiniMessage
• Full PlaceholderAPI support
• Full configuration in config.yml
• Hot reload without restarting the server
• Automatic color format detection
  • If the nick contains < → MiniMessage
  • Otherwise → Legacy

Commands
Command Description Permission
/nick Change your own visible nickname customnick.use
/nick reset Restore your original name customnick.use
/nick set <player> <nick> Change another player's nickname customnick.admin
/nick reset <player> Reset another player's nickname customnick.admin
/nick reload Reload config.yml in hot customnick.admin
Alias: /nickname

️ Permissions
Permission Default Description
customnick.use op Use /nick to change your own nickname
customnick.color op Use Legacy color codes (&a, &#FF0000)
customnick.minimessage op Use MiniMessage tags (<gradient:red:blue>, etc.)
customnick.admin op Manage other players’ nicknames and reload config
Color Formats

• Legacy (basic)
  
  
  /nick &aHeroName
  /nick &c&lAdmin
  /nick &eGuest&r
  
  
• Legacy Hex
  
  
  /nick &#FF4400Steve
  /nick &#00AAFFCool&#FFFFFFName
  
  
• MiniMessage
  
  
  /nick <gradient:red:blue>Hero</gradient>
  /nick <#FF0000>Admin</#FF0000>
  

Allowed MiniMessage tags: color, decorations, gradient, rainbow, reset
Blocked tags: click, hover, insertion, font, and similar for security

⚙️ Configuration (config.yml)

nick:
min-length: 3
max-length: 16
colors:
legacy-enabled: true
minimessage-enabled: true

Apply changes without restarting the server: /nick reload

PlaceholderAPI Placeholders
Automatically registered if PlaceholderAPI is installed:

Placeholder Description
%customnick_nick% Nickname with § colors for chat, tab, etc.
%customnick_nick_raw% Raw nickname as stored (Legacy & MiniMessage codes)
%customnick_hasNick% true if the player has a custom nick, false otherwise
Examples:

• Chat (LPC format): <%customnick_nick%> {message}
• Tablist name: %customnick_nick%
• Nametag prefix: %customnick_nick%

Storage
Nicknames are saved in plugins/CustomNick/nicks.yml:

nicks:
550e8400-e29b-41d4-a716-446655440000: "&aHeroName"
6ba7b810-9dad-11d1-80b4-00c04fd430c8: "gradient:red:blueAdmin"

The file updates automatically on every change and on server shutdown.

Project Structure

src/main/
├── java/com/tuservidor/customnick/
│ ├── CustomNick.java # Main class
│ ├── config/ConfigManager.java # Config reader & cache
│ ├── command/NickCommand.java # /nick command & tab completer
│ ├── listener/PlayerJoinListener.java # Restore nick on join
│ ├── manager/NickManager.java # Validation & application logic
│ ├── placeholder/CustomNickExpansion.java # PlaceholderAPI expansion
│ └── storage/NickStorage.java # YAML persistence
└── resources/
├── plugin.yml
└── config.yml

Final Note
Thank you for downloading this plugin
For support or questions, contact: [email protected]