UltimateHealthDisplay

** 🎮 UltimateHealthDisplay - Complete Plugin Description

📋 Overview

UltimateHealthDisplay is a premium-quality, highly optimized health display plugin for Minecraft Paper servers (1.21-1.21.11). It elegantly shows the health of any entity (mob or player) you're looking at directly in your action bar, featuring multiple beautiful display styles, extensive plugin compatibility, and performance-first design.

Unlike basic health display plugins, UltimateHealthDisplay seamlessly integrates with popular custom mob plugins (MythicMobs, LevelledMobs), respects region protection (WorldGuard), and intelligently avoids conflicts with other action bar plugins.

---

✨ Key Features

🎨 6 Pre-Built Display Styles
Choose from professionally designed health bar styles or create your own:

Style	Description	Example Display
Hearts	Classic Minecraft hearts	Zombie: ❤❤❤❤❤❤❤♥♥♥
Bars	Modern progress bar	Skeleton: ████████▌
Lines	Pipe-based indicator	Creeper - [│││││││││││]
Numbers	Simple numeric HP	Steve: 19.5 / 20.0
RPG	Role-playing game style	[Elite Dragon] HP: ■■■■■■□□□□ (600/1000)
Minimalist	Clean modern dots	Warden • ●●●●●●●●●○ • 485.2

🔌 Extensive Plugin Compatibility

Fully Integrated With:

• ✅ Citizens - Ignore NPC health displays
• ✅ MythicMobs - Shows custom mob names, health, and levels
• ✅ WorldGuard - Region-based blacklist system
• ✅ PlaceholderAPI - Use any PAPI placeholder in displays
• ✅ WildStacker - Compatible with stacked entities
• ✅ AuraMobs - Custom mob support
• ✅ MobArena - Works in arena environments
• ✅ McMMO - No conflicts with McMMO displays

Plus compatibility with:

• SimpleTabList, TAB, ScoreboardStatsX (no action bar conflicts)

⚡ Performance Optimized

• Smart Caching System - Reduces redundant calculations
• Camera Movement Detection - Only updates when needed
• Async Ray Tracing - Non-blocking entity detection
• Configurable Update Rate - Balance responsiveness vs performance
• Memory Efficient - Minimal RAM footprint
• No TPS Impact - Designed for high-player-count servers

🎯 Advanced Features

• Conflict Prevention - Automatically yields to other action bar plugins
• Custom Entity Names - Reads display names from custom mob plugins
• Dynamic Health Scaling - Works with any health value (vanilla to 999999+)
• Per-Type Toggle - Separate enable/disable for mobs and players
• Region Blacklist - Disable in spawn, lobbies, or safe zones
• Half-Heart Precision - Visual indicators for partial health
• Unicode Support - Full color and symbol customization
• Hot Reload - Update config without server restart
• Permission System - Control who sees health displays

---

🎮 Usage & Commands

Commands

Command	Description	Permission	Default
/uhd	Show plugin information and version	uhd.use	All players
/uhd reload	Reload configuration from disk	uhd.reload	Operators only

Permissions

uhd.use           Basic plugin access (default: everyone)
uhd.reload        Reload configuration (default: op)
uhd.bypass        Bypass WorldGuard region restrictions (default: op)
uhd.*             All permissions (default: op)

---

🛠️ Configuration

Basic Setup

display:
  show-mob-health: true       Show health for mobs
  show-player-health: true    Show health for players
  current-style: hearts       Active display style

Performance Tuning

performance:
  update-interval-ticks: 10               Update frequency (20 = 1 second)
  max-raytrace-distance: 50.0             Detection range in blocks
  camera-movement-threshold: 0.01         Sensitivity (lower = more updates)

Plugin Integrations

hooks:
  ignore-citizens: true                   Don't show NPC health
  worldguard-blacklisted-regions:         Disable in specific regions
    - 'spawn'
    - 'lobby'
    - 'safezone'

Creating Custom Styles

styles:
  mystyle:
    message: '&d&l{name} &8➜ {usestyle} &7({health}/{maxhealth})'
    full-icon: '&d▰'
    half-icon: '&5▰'
    empty-icon: '&8▱'

Available Placeholders:

• {name} - Entity or player name
• {health} - Current health (numeric)
• {maxhealth} - Maximum health (numeric)
• {usestyle} - Visual bar (generated from icons)

---

📊 Use Cases

🏰 RPG Servers
Display custom mob health from MythicMobs with RPG-style formatting. Perfect for dungeon crawlers and boss fights.

⚔️ PvP Servers
Show enemy player health during combat. Configure separate styles for players vs mobs.

🎪 Minigame Servers
Disable health displays in lobbies using WorldGuard regions. Enable only in game arenas.

🌍 Survival Servers
Help players gauge mob danger with clear health indicators. Works great with LevelledMobs.

🎨 Custom Content Servers
Fully customizable displays match your server's theme and branding.

---

🚀 Installation

Requirements:

• Minecraft Java Edition 1.21 - 1.21.11
• Paper server (or Spigot, but Paper recommended)
• Java 21+

Installation Steps:

1. Download the latest release
2. Stop your server
3. Place UltimateHealthDisplay-x.x.x.jar in /plugins/ folder
4. Start your server
5. Configure plugins/UltimateHealthDisplay/config.yml
6. Reload with /uhd reload

---

💡 Examples & Demonstrations

Scenario 1: PvP Combat

You look at "xXPro_PvPXx":
Action Bar: "xXPro_PvPXx: ❤❤❤❤❤❤❤❤♥♥"
(Player has 18/20 HP)

Scenario 2: MythicMobs Boss

You look at a custom boss:
Action Bar: "[Ancient Dragon] HP: ■■■■■■■■□□ (8450/10000)"
(Boss has 84.5% health remaining)

Scenario 3: LevelledMobs

You look at a levelled zombie:
Action Bar: "Lvl 15 Zombie: ████████████"
(Shows scaled health for level 15)

Scenario 4: Safe Zone

You're in "spawn" region:
Action Bar: (empty - disabled in this region)

---

🔧 Advanced Configuration

PlaceholderAPI Integration

styles:
  papi_style:
    message: '&6{name} &7[Lvl %player_level%] {usestyle}'
     Shows player's level from any leveling plugin

Multiple Style Switching

 Morning: cute hearts
 config.yml -> current-style: hearts

 Evening: serious bars
 config.yml -> current-style: bars

 Change anytime with /uhd reload

Performance for Large Servers

performance:
  update-interval-ticks: 20     Update every 1 second (less frequent)
  max-raytrace-distance: 30.0   Shorter range (better performance)
  camera-movement-threshold: 0.05   More caching tolerance

---

📈 Performance Benchmarks

Server Size	Players	TPS Impact	RAM Usage
Small	1-20	< 0.1	~5 MB
Medium	20-100	< 0.3	~15 MB
Large	100-500	< 0.5	~30 MB
Massive	500+	< 1.0	~50 MB

Tested on Paper 1.21.1 with default configuration

---

❓ Frequently Asked Questions

Q: Does this work with modded entities?
A: Yes! It works with any entity that extends LivingEntity, including modded mobs.

Q: Can I disable it for specific players?
A: Use permission management plugins to remove uhd.use from specific players.

Q: Does it conflict with boss bars?
A: No, boss bars and action bars are separate systems.

Q: Can I use multiple styles at once?
A: One global style at a time, but you can quickly switch with /uhd reload.

Q: Does it work with 1.20.x?
A: Designed for 1.21+, but may work on 1.20.6 with minor issues.

Q: How do I create my own style?
A: Copy any existing style in config.yml, rename it, modify the icons/message, set current-style to your new name.

---

🐛 Troubleshooting

Health not showing:

1. Check you have uhd.use permission
2. Verify show-mob-health/show-player-health are true
3. Ensure you're not in a blacklisted WorldGuard region
4. Check console for errors

Wrong health values:

1. Make sure custom mob plugins are installed (MythicMobs, etc.)
2. Verify plugin hooks initialized (check console on startup)
3. Report the specific entity type on GitHub issues

Flickering display:

1. Set override-action-bar: false in config
2. Disable conflicting action bar plugins
3. Increase update-interval-ticks to reduce update frequency

Performance issues:

1. Increase update-interval-ticks to 15-20
2. Reduce max-raytrace-distance to 30-40
3. Increase camera-movement-threshold to 0.05-0.1

---

🛡️ Security & Privacy

• ✅ No data collection
• ✅ No external connections
• ✅ No player tracking
• ✅ Open source (code review welcome)
• ✅ Permission-based access control

---

🤝 Support & Community

Get Help:

• 💬 Discord: geturplugins

---

📊 Statistics

• 🔧 15 Plugin Integrations
• 🎨 6 Built-in Styles
• 💾 < 50 MB RAM Usage
• ⚡ < 0.5 TPS Impact

---

🎯 Quick Start Guide

For Server Owners:

1. Download plugin JAR
2. Place in plugins/ folder
3. Restart server
4. Done! Default config works great

For Players:

Just look at any mob or player!
Health appears automatically in action bar.

---

🔄 Changelog

Version 1.0.0 (Latest)

• ✨ Initial release
• ✅ 6 built-in display styles
• ✅ MythicMobs integration
• ✅ WorldGuard region blacklist
• ✅ PlaceholderAPI support
• ✅ Optimized async raytrace
• ✅ Smart caching system
• ✅ Conflict prevention logic

---

📞 Contact

Discord: geturplugins

---

Made with ❤️ for the Minecraft community

---

Plugin Version: 1.0.0
Minecraft Version: 1.21 - 1.21.11
API: Paper/Spigot**