NetworkNick

NetworkNick is a lightweight, network-aware nickname plugin for Paper and Spigot that provides persistent, Redis-backed nicknames with full support for PlaceholderAPI, LuckPerms, and modern multi-server environments.

Designed for modern servers and proxy networks, NetworkNick focuses on correctness, timing, and compatibility — ensuring nicknames apply before join messages, sync instantly across servers, and respect offline permissions.

---

Changelog

1.0.1

• Network-wide nicknames via Redis
• Join-time correctness (%player_displayname% works in join messages)
• Offline-safe nickname exemption (LuckPerms integration)
• Hide / unhide system with prior nickname restoration
• Robust enforcement against late plugin overrides
• PlaceholderAPI support
• Clean reload support
• Paper & Spigot compatible (no NMS, no ProtocolLib)

---

Overview

NetworkNick allows players to set nicknames that:

• Persist across restarts and reconnects
• Synchronize instantly across multiple backend servers
• Appear correctly in join messages, chat, TAB, and scoreboards
• Respect permissions, formatting rules, and offline exemptions

The plugin is built around a Redis source of truth, with careful handling of join timing to ensure %player_displayname% always reflects the correct nickname.

---

Core Features

Nicknames

• Set custom nicknames with /nick
• Supports legacy color codes (&a) and hex colors (&#RRGGBB)
• Optional formatting permissions (&l, &o, &k, etc.)
• Safe length enforcement (3–16 visible characters)

Hide / Unhide

• /hide obfuscates your name using &k
• /unhide restores your previous nickname or real name
• Prior nicknames are stored safely and restored correctly

Network Sync

• Redis-backed nickname storage
• Real-time updates across all servers
• Automatic re-application on join, reload, and reconnect

Exempt Players

• networknick.exempt prevents other players from changing or unhiding your nickname
• Uses the LuckPerms API to check permissions even when the player is offline
• Safe asynchronous handling (no main-thread blocking)

Enforcement System

• Optional short-term enforcement to beat late plugin overrides
• Protects against plugins that reset display names after join

Placeholder Support

• PlaceholderAPI integration
• Custom placeholders for network-aware name handling

---

Requirements

• Java 21
• Paper or Spigot 1.20+
• Redis server (required)
• Optional but recommended: LuckPerms
• Optional: PlaceholderAPI

---

Installation

Single-Server Setup

1. Download NetworkNick-1.0.0.jar
2. Place it in your server’s plugins/ directory
3. Start the server
4. Configure permissions (LuckPerms recommended)
5. Restart or run /networknick reload

---

Multi-Server Setup

Recommended for Velocity or BungeeCord environments.

Requirements

• Shared Redis instance
• Identical plugin configuration across all backend servers

Steps

1. Configure Redis connectivity
2. Ensure all backend servers connect to the same Redis instance
3. Restart all servers

Features

• Network-wide nicknames
• Instant synchronization across servers
• Consistent join messages everywhere

Redis acts as the source of truth
Local caches are ephemeral and safe

---

Commands

Player Commands

Command	Description	Permission
/nick <name>	Set your nickname	networknick.nick
/nick off	Clear your nickname	networknick.nick.clear
/hide	Hide your name	networknick.hide
/unhide	Restore your name	networknick.unhide

Admin Commands

Command	Description	Permission
/nick <player> <name>	Set another player’s nickname	networknick.nick.others
/nick <player> off	Clear another player’s nickname	networknick.nick.others.clear
/unhide <player>	Unhide another player	networknick.unhide.others
/networknick reload	Reload config and Redis	networknick.reload

---

Permissions

Core

Permission	Description	Default
networknick.nick	Use /nick	op
networknick.nick.clear	Clear own nickname	op
networknick.hide	Use /hide	op
networknick.unhide	Use /unhide	op

Moderation

Permission	Description
networknick.nick.others	Set others’ nicknames
networknick.nick.others.clear	Clear others’ nicknames
networknick.unhide.others	Unhide others

Formatting

Permission	Description
networknick.nick.colors	Color and hex codes
networknick.nick.format.k	Obfuscated
networknick.nick.format.l	Bold
networknick.nick.format.m	Strikethrough
networknick.nick.format.n	Underline
networknick.nick.format.o	Italic
networknick.nick.format.r	Reset

Protection

Permission	Description
networknick.exempt	Prevent others from changing or unhiding your nickname

---

(PlaceholderAPI)

Placeholder	Description
%networknick_name%	Visible nickname (or real name)
%networknick_unhidden%	Real name or prior nickname
%networknick_hidden%	true or false

Note: %player_displayname% will also reflect the nickname, as NetworkNick applies it before join messages are processed. Just make sure if you're using essentials you have change-displayname set to false in their config.

---

Planned Enhancements

• None currently. Open to suggestions

---

License

Licensed under the Apache License, Version 2.0
See LICENSE for details.

---

Credits

Developed by Chumbucket
Built for the Chumbucket Network
https://www.chumbucket.net

© 2025 Chumbucket — Apache-2.0 License