Configuration¶

Nicked's behaviour is controlled by plugins/Nicked/config.yml, which is generated with defaults on first start. You can edit it while the server is running, but changes require a server restart (or plugin reload if your server supports it) to take effect.

Full Default Config¶

# ============================================================
# Nicked - Configuration
# ============================================================

# ============================================================
# DANGER ZONE - READ CAREFULLY BEFORE ENABLING
# ============================================================
# When enabled, Nicked will modify the server-side GameProfile
# for each nicked player via reflection. This means:
#   - ALL other plugins will see the fake name as the real name
#   - /tp, /msg, /give, etc. will resolve to the fake name
#   - Plugins that store data by player name WILL be confused
#   - Data corruption is possible if other plugins save by name
# This is disabled by default. USE AT YOUR OWN RISK.
# ============================================================
internal_name_change:
  enabled: false

# Keep nicks active after the server restarts.
# Nicks are written to plugins/Nicked/nicks.yml on change.
persist_across_restarts: false

# Keep nicks active when a player logs out and back in.
# If persist_across_restarts is also true, this survives restarts too.
persist_across_logout: false

# Also change the skin for the nicked player themselves
# (requires a brief respawn packet sent to the player).
skin_change_for_self: true

# When a nick's skin cannot be fetched from Mojang (unknown/non-premium name,
# rate limit, or timeout), strip the player's real skin so viewers see the
# default (Steve/Alex) skin instead of the recognizable real one. Disabled by default.
skin_fallback_on_fetch_failure: false

# ------------------------------------------------------------
# Hide the real name in server broadcasts
# ------------------------------------------------------------
# By default Minecraft builds these messages from the real server-side name,
# not the nick, so each one below can reveal a nicked player. Enable the ones
# you want rewritten to use nick names. All disabled by default.

# "<name> was slain by ..." (covers the victim and a player killer).
death_messages:
  use_nick_names: false

# "<name> joined the game".
join_messages:
  use_nick_names: false

# "<name> left the game".
quit_messages:
  use_nick_names: false

# "<name> has made the advancement [X]" (task / goal / challenge).
advancement_messages:
  use_nick_names: false

# Enforce that nick names are valid Minecraft usernames:
# 3-16 characters, alphanumeric and underscores only.
strict_name_validation: true

# How long to cache fetched skins from the Mojang API (in minutes).
# Mojang rate limits at 600 requests per 10 minutes.
# Must be greater than 0.
skin_cache_ttl_minutes: 30

# Pool of names to pick from for /nick (no args) and /nickall.
# Leave empty to fall back to currently online player names.
random_nick_pool:
  - Notch
  - jeb_
  - Dinnerbone
  - Herobrine
  - Dream
  - Technoblade

Option Reference¶

`internal_name_change.enabled`¶

Key	Type	Default
`internal_name_change.enabled`	Boolean	`false`

Danger zone

Enabling this option modifies the server-side GameProfile for each nicked player using Java reflection. The consequences are significant:

Every other plugin on the server will see the fake name as if it were the player's real name.
Built-in commands such as /tp, /msg, /give, and /kick will resolve to the fake name.
Plugins that store player data keyed by username (not UUID) will be confused and may corrupt their data.
When Nicked is disabled or the player is unnicked, the original GameProfile is restored. However, any external data that was written during the nick session using the fake name will not be corrected automatically.

This option exists for rare use cases where full server-side name hiding is required and the implications are understood and accepted. Leave it false unless you are certain you need it.

`persist_across_restarts`¶

Key	Type	Default
`persist_across_restarts`	Boolean	`false`

When true, the plugin writes each nick change to plugins/Nicked/nicks.yml and reads it back when the server starts. Players who were nicked when the server shut down will have their nick reapplied 5 ticks after they log in.

The stored data includes the nicked name, the original skin, the nicked skin, the cause, and the timestamp.

`persist_across_logout`¶

Key	Type	Default
`persist_across_logout`	Boolean	`false`

When true, a player's nick is kept in memory even after they disconnect. When they rejoin, the nick is reapplied automatically (5-tick delay to allow the join process to complete).

Combine with persist_across_restarts: true to survive both logouts and server restarts.

`persist_across_logout`	`persist_across_restarts`	Nick survives…
`false`	`false`	Nothing — nick is always lost on logout
`true`	`false`	Player disconnecting and reconnecting in the same server session
`true`	`true`	Player disconnecting and reconnecting, plus full server restarts

`skin_change_for_self`¶

Key	Type	Default
`skin_change_for_self`	Boolean	`true`

When true, Nicked sends the nicked player a sequence of packets (a PLAYER_INFO_REMOVE followed by PLAYER_INFO_UPDATE, and then a same-dimension RESPAWN) so they see their own new skin in first-person and on the pause screen. Without this, the player would see their old skin in their own client even though everyone else sees the new one.

The respawn packet approach causes a brief screen flash but does not teleport the player or change their inventory/state.

Set to false if you prefer to avoid the respawn packet, accepting that the nicked player will not see their own new skin locally.

`skin_fallback_on_fetch_failure`¶

Key	Type	Default
`skin_fallback_on_fetch_failure`	Boolean	`false`

The nick skin is fetched from Mojang by the nick name. If that fetch fails — the nick isn't a premium account, Mojang rate-limits, or the request times out — the nick name is still applied, but with no skin change. Without this option, the player's real (often recognizable) skin keeps rendering under the fake name, which is a direct visual tell.

When true, a failed skin fetch instead strips the texture entirely, so viewers see the default Steve/Alex skin rather than the real one.

Broadcast rewrites: `death_messages`, `join_messages`, `quit_messages`, `advancement_messages`¶

Key	Type	Default
`death_messages.use_nick_names`	Boolean	`false`
`join_messages.use_nick_names`	Boolean	`false`
`quit_messages.use_nick_names`	Boolean	`false`
`advancement_messages.use_nick_names`	Boolean	`false`

Minecraft builds these four broadcasts from the server-side player name, not the tab-list profile that Nicked rewrites. So each one shows a nicked player's real name to everyone — for example Notch123 was slain by a Zombie, Notch123 joined the game, or Notch123 has made the advancement [Stone Age] — revealing the nick.

Enable any of these to have Nicked replace the real name of every currently-nicked player with their nick name in that broadcast. They are independent so you can turn on only the ones you want. Name matching is whole-word and case-sensitive, so unrelated text is left untouched.

death_messages — covers both the player who died and a player killer named in the message. Rewritten at HIGHEST priority, after any custom death-message plugin.
join_messages / quit_messages — cover the "joined/left the game" lines, including persisted nicks that are re-applied on login.
advancement_messages — covers "has made the advancement/goal/challenge" announcements. Because there is no Bukkit API for these, they are rewritten at the packet level; the player-name argument is rebuilt as plain text, which also drops the hover/click payload that would otherwise still carry the real name and UUID.

These are not the only leaks

Rewriting these broadcasts does not make a nick bulletproof. A player's real UUID is still sent to clients (resolvable via a client mod or NameMC), and server-side integrations (web maps, Discord bridges, %player_name% in other plugins, /list, whispers) read the real name unless internal_name_change is enabled. These broadcasts are simply the most visible, zero-tool leaks.

`strict_name_validation`¶

Key	Type	Default
`strict_name_validation`	Boolean	`true`

When true, nick names must match the regular expression ^[a-zA-Z0-9_]{3,16}$ — the same rules Mojang enforces for real Minecraft usernames:

Minimum 3 characters
Maximum 16 characters
Only letters (A–Z, a–z), digits (0–9), and underscores (_)

Set to false to allow any string as a nick name. Note that non-standard names (e.g. names with spaces or special characters) may cause visual glitches in the tab list or chat on some client versions.

`skin_cache_ttl_minutes`¶

Key	Type	Default	Minimum
`skin_cache_ttl_minutes`	Integer	`30`	`1`

Skins fetched from the Mojang API are cached in memory for this many minutes. When a cached entry expires and the same nick is applied again, a fresh request is made to the API.

Mojang's rate limit is 600 requests per 10 minutes per IP address. With the default TTL of 30 minutes, a frequently used nick name will only incur one API call every 30 minutes regardless of how many players use it.

The plugin validates this value on startup and disables itself if it is set to 0 or a negative number.

`random_nick_pool`¶

Key	Type	Default
`random_nick_pool`	List of Strings	`[Notch, jeb_, Dinnerbone, Herobrine, Dream, Technoblade]`

The list of names that /nick (no arguments) and /nickall draw from when picking a random nick.

At runtime, Nicked merges this list with the names of currently online players (deduplicated) to build the full candidate pool. The player's own real name is excluded from the pool to prevent them from being "nicked" as themselves.

If this list is empty and no other players are online (other than the player requesting the random nick), the command fails with the no_random_pool message.

# Example: a large pool of well-known Minecraft personalities
random_nick_pool:
  - Notch
  - jeb_
  - Dinnerbone
  - Herobrine
  - Dream
  - Technoblade
  - xNestorio
  - Grian
  - Mumbo
  - iskall85

Tip

You can listen to NickRandomSelectEvent in your own plugin to replace or override the selected name at runtime without modifying this file.

Configuration¶

Full Default Config¶

Option Reference¶

internal_name_change.enabled¶

persist_across_restarts¶

persist_across_logout¶

skin_change_for_self¶

skin_fallback_on_fetch_failure¶

Broadcast rewrites: death_messages, join_messages, quit_messages, advancement_messages¶

strict_name_validation¶

skin_cache_ttl_minutes¶

random_nick_pool¶