AddHeads

AddHeads is a lightweight Paper/Purpur plugin for servers that adds player heads in chat and in the in-game tab list. It also provides reusable head placeholders for custom integrations. NO RP AND MOD NEEDED

🚀 Just Download and it works!

No additional plugin settings for chat and tab - the plugin works on top of them.
Everything works on a vanilla client, does not require any resource pack or mods.

🌍 Languages

Bundled languages:

en-us | es-es | de-de | fr-fr | pt-br | zh-cn | ru-ru

✨ What it does

• automatically prepends the player's head to the in-game player list name
  
• keeps working with vanilla player lists and with tab-related plugins without manual placeholder insertion even in offline mod
• adds the player's head before the chat message
  
• preserves existing chat formatting from other plugins
• supports shared skin resolution with SkinsRestorer when available
• keeps a single reusable skin cache for chat and placeholders
• includes a localized /hd settings GUI for admins

⚙️ Features

• Vanilla chat head rendering
• automatic player-list head insertion without extra setup
• public Bukkit service API for other plugins
• PlaceholderAPI support with multiple export formats
• SkinsRestorer-aware skin lookup
• automatic skin and cache refresh
• personal chat and player-list visibility toggles
• localized settings GUI
• live config and language reload
• automatic config and language key backfill on reload
• configurable spacing between the head and the text in both chat and the player list
• separate shadow settings for chat heads and player-list heads
• update checks from GitHub and Modrinth

💬 SUPPORTS ANY CHAT PLUGIN

🧩 Supported Player List Plugins

AddHeads supports these player-list plugins directly:

• TAB

  Native support is implemented through the TAB API, so heads are added correctly even when TAB formats prefixes, suffixes, colors, and tab list names.

• CMI / PowerBoard / PowerBoard / Any other

  Supported through the standard compatibility path.

AddHeads also works with other player-list plugins that do not block external tab list modifications.

If a plugin allows the final tab list name to be modified externally, AddHeads can usually prepend the head through its normal compatibility path. For TAB, native API integration is used instead, so heads are rendered correctly even with TAB formatting features enabled.

📋 Requirements

• Paper or Purpur 1.21.9+
• Java 21

🔌 Optional dependencies

• PlaceholderAPI
• SkinsRestorer

🛠 Commands

Command	Description	Permission
/hd togglechat	Toggles chat heads for the executing player.	addhead.togglechat
/hd toggletab	Toggles tab heads for the executing player.	addhead.toggletab
/hd settings	Opens the localized config GUI.	addhead.settings
/hd info	Shows plugin name, version, and author.	None
/hd reload	Reloads config, language files, and skin cache.	addhead.reload

🔐 Permissions

• addhead.togglechat - Allows toggling your own chat heads.
• addhead.toggletab - Allows toggling your own tab heads.
• addhead.settings - Allows opening the settings GUI.
• addhead.reload - Allows reloading the plugin and using repair actions.
• addhead.premium - Used only when premium.mode=permission.

📦 Installation

1. Download AddHeads-{version}.jar.
2. Place it in your server plugins/ folder.
3. Start or restart the server.
4. Edit config.yml and languages/*.yml or use /hd settings if needed.
5. Use /hd reload after making changes.

📝 Notes

• AddHeads does not force one specific chat formatter.
• It decorates the final chat component after other chat plugins finish formatting it.
• The default tab path does not require any placeholder setup.
• The tab head is inserted automatically through the in-game player list name.
• This works with vanilla player lists and is designed to keep working even if another tab-related plugin rewrites the list name later.
• PlaceholderAPI placeholders are still available for custom layouts, prefixes, scoreboards, and similar UI.
• New language keys and config keys are backfilled automatically from the bundled defaults on reload.

🧠 Placeholders

• %addhead_head% - JSON component head for chat and component-aware plugins.
• %addhead_tab% - Optional tab head placeholder for custom PlaceholderAPI-based layouts.
• %addhead_texture_value% - Raw texture value.
• %addhead_texture_signature% - Raw texture signature.
• %addhead_texture_hash% - textures.minecraft.net hash.
• %addhead_skin_ready% - true or false, whether the shared skin cache already has a confirmed skin.
• %addhead_tab_visible% - true or false, whether tab head output is enabled for that player.

🎨 Skin Sources

AddHeads resolves skins in this order:

1. SkinsRestorer
2. live Paper player profile
3. Paper profile update lookup
4. Mojang profile/session lookup by player name
5. cached value already resolved by AddHeads

💫 My Other Plugins:

• PremiumBridge - auto-authenticate premium players (Supports AddHeads)
• PointCoordinates - save important places, keep coordinates organized