👤 LayerHeads

LayerHeads is an ultra-optimized, feature-packed player head and head command plugin for Paper and Purpur servers running on Java 21 to 25 and Minecraft versions 1.21 through 26.x. It allows players to fetch custom skins for both Official Mojang (Original) and SkinsRestorer (Warez) players with persistent metadata, manage their personal head histories through a clean GUI, and gives server administrators the power to turn any placed player head into an interactive, indestructible command trigger!

It is the perfect addition to survival, RPG, lobby, hub, and adventure servers—ideal for interactive NPC heads, clickable reward pedestals, hidden proximity easter eggs, quest triggers, and more!

---

✨ Key Features

• ⚡ Instant Real-Time SkinsRestorer Synchronization:
  • Full native integration with SkinsRestorer
  • Automatically captures skin changes in real-time when players execute /skin <name> or /skin url.
  • Zero-delay cache invalidation ensures that the very next /lh get command immediately provides the updated custom skin without waiting for TTL expiration!
• 🏷️ Intelligent Account Origin Classification ({type}):
  • &aOriginal: Verified official Mojang accounts fetched directly from official Mojang session servers.
  • &cWarez: Offline/cracked accounts, live online server profiles, or custom skins set via SkinsRestorer.
  • &eDefault: Automatic Steve/Alex fallback if no skin exists on Mojang or SkinsRestorer.
  • All type labels and colors are fully customizable in config.yml!
• 🌈 MiniMessage & Legacy Color Support:
  • Full support for Kyori MiniMessage formatting tags (<green>, <gray>, <gradient:#55ff55:#00aa00>, <rainbow>, <bold>, <italic>, etc.) alongside classic Legacy & Hex colors (&a, &b, &7, &#55ff55, &x&r&r&g&g&b&b).
• 🔢 Clean 6-Digit Head IDs & Aesthetic Lore Cards:
  • Generates clean 6-digit identification numbers (e.g. #{id} ➔ #849201) and compact date formats (26.08.2026 21:00) with customizable borders and placeholders.
• 📜 Multi-Skin History GUI (/lh history):
  • Keeps distinct skin versions for the same player name—if a player changes their skin, both heads are preserved as separate entries!
  • Clicking any head in the history menu gives you the exact historical head and skin texture.
• 🎮 Interactive Head Commands:
  • Attach multiple sequential console and player commands to any placed player head block with customizable execution order!
• ⚡ Click & Proximity Triggers:
  • Trigger head commands by clicking or when players enter a configurable radius (with smart entry/exit detection that triggers once per entry).
• 🛡️ Indestructible & Floating Heads:
  • Heads with assigned commands are protected against player breaking, explosions, and physics updates.
• 🎯 Advanced Condition & Selector Engine:
  • Full support for vanilla command block syntax, target selectors (@p, @s, @a, @r), scoreboards (score=points:5..), tags (tag=vip), levels, gamemodes, and /execute if ....
• 📦 2D Inventory Heads:
  • Automatically deploys flat 2D head item models for ItemsAdder, Nexo, or Oraxen resource pack pipelines.
• **🚀 Ultra-Low Resource Footprint **:
  • Engineered for high-load production servers with 100+ concurrent players.
  • Asynchronous debounced storage I/O, bounded self-cleaning skin cache, and 0ms disk lookups.
• 🔄 Built-in Modrinth Update Checker:
  • Hardcoded async update checker notifies server administrators upon login with clickable download links.

---

🚀 How It Works

Fetching Heads:

1. Type /lh get <player_name> to fetch any Minecraft player's skin head (works for both Mojang Original and SkinsRestorer Warez accounts!).
2. The head is added to your inventory with an aesthetic custom lore card, 6-digit ID, timestamp, and account origin tag (&aOriginal, &cWarez, or &eDefault).
3. Open /lh history at any time to view and re-give previously fetched heads from your personal history!

Creating Command Triggers:

1. Place any player head on the ground or against a wall.
2. Look at the head (within 5 blocks) and set a trigger:
   • /lh cmd trigger click (triggers on interaction)
   • /lh cmd trigger proximity 5 (triggers when players enter within 5 blocks)
3. Add sequential commands:
   • /lh cmd add 1 console tellraw %player% {"text":"Welcome to the secret area!","color":"aqua"}
   • /lh cmd add 2 player tag=vip me collected their VIP bonus!
   • /lh cmd add 3 console give %player% diamond 1
4. The head is now permanently protected, indestructible, and floats in mid-air if the surrounding blocks are broken!

---

💻 Commands & Aliases

Command Aliases: /lh, /layerheads, /head, /heads, /lhead, /lheads

Player Commands:

• /lh get <player_name> — Fetches the player head with custom skin and metadata.
• /lh history — Opens your personal head fetch history menu.

Admin & Command Block Commands:

• /lh cmd add <id> <player|console> <command...> — Adds a command with a sequential ID.
• /lh cmd set <id> <player|console> <command...> — Modifies/replaces an existing command.
• /lh cmd remove <id> — Removes a specific command from the targeted head.
• /lh cmd list — Lists all commands and trigger settings configured on the targeted head.
• /lh cmd trigger <click|proximity> [radius] — Sets the trigger action and optional radius.
• /lh cmd clear — Clears all commands and removes protection from the targeted head.
• /lh reload — Reloads configuration, storage, and 2D resource pack integrations.

---

⚙️ Permissions

layerheads.admin:
  description: Full administrator access to all LayerHeads features.
  default: op

layerheads.use:
  description: Allows fetching heads and opening personal history.
  default: true

layerheads.command.get:
  description: Allows using /lh get <player>.
  default: true

layerheads.command.history:
  description: Allows using /lh history.
  default: true

layerheads.command.cmd:
  description: Allows managing commands on head blocks.
  default: op

layerheads.command.cmd.add:
  description: Allows adding commands to head blocks.
  default: op

layerheads.command.cmd.set:
  description: Allows modifying commands on head blocks.
  default: op

layerheads.command.cmd.remove:
  description: Allows removing commands from head blocks.
  default: op

layerheads.command.cmd.list:
  description: Allows viewing commands on head blocks.
  default: op

layerheads.command.cmd.trigger:
  description: Allows setting trigger mode on head blocks.
  default: op

layerheads.command.cmd.clear:
  description: Allows clearing commands from head blocks.
  default: op

layerheads.command.reload:
  description: Allows reloading plugin configuration (/lh reload).
  default: op

---

🧩 Command Syntax & Conditions

When configuring head commands, you can prefix commands with conditions or use full vanilla selector arguments:

Condition Syntax	Description	Example
tag=<name>	Player must have the scoreboard tag	tag=vip say Hello VIP!
tag=!<name>	Player must NOT have the scoreboard tag	tag=!member kick %player%
score=<obj>:<range>	Player's score must match integer range	score=coins:10.. give %player% diamond 1
scores={<obj>=<val>}	Multi-objective condition block	scores={level=5..,coins=100..} say High level!
level=<range>	Player EXP level condition	level=10.. title %player% actionbar {"text":"Level 10!"}
gamemode=<mode>	Player gamemode condition	gamemode=survival heal %player%
permission=<node>	Player permission node condition	permission=group.hero say Welcome hero!
[cond1,cond2]	Bracketed compound conditions	[tag=vip,score=coins:50] give %player% emerald 1

Available Item & Command Placeholders:

• {id} or %id% — Clean 6-digit numeric identification ID (e.g. 849201)
• {type} or %type% — Account / skin origin (&aOriginal, &cWarez, &eDefault)
• {date} or %date% — Compact creation date & time (e.g. 26.08.2026 21:00)
• {time} or %time% — Time only (e.g. 21:00)
• {short_date} or %short_date% — Short date (e.g. 26.08.26)
• {player} or %player% — Player username
• {world} or %world% — World name of the head block
• {x}, {y}, {z} — Coordinates of the head block
• Full PlaceholderAPI support if installed on your server!

---

🔧 Compatibility & Dependencies

• Java Versions: Java 21, Java 25
• Server Software: Paper, Purpur
• Minecraft Versions: 1.21 to 26.x
• SkinsRestorer (Supported)
• LuckPerms & Vault (Supported)
• PlaceholderAPI (Optional)
• ItemsAdder / Nexo / Oraxen (Optional)