CNPC+ Health Bars Addon

A customizable health bar addon made specifically for CustomNPC+ on Minecraft 1.7.10.

It adds polished world-space NPC health bars, faction defaults, per-NPC overrides, Custom Boss Bars, smooth combat feedback, shields, boss phases, same-name health-bar linking, client-side layout controls, and a public scripting API.

---

Features

• Health bars above CustomNPC+ NPCs.
• Main world-bar display modes:
  • Faction
  • Show
  • Hide
  • On Hit
• Faction-based health bar configuration.
• Full per-NPC health-bar editor with property-based overrides.
• Unchanged per-NPC properties can continue inheriting from the NPC's faction.
• HP Color can use the faction palette or a completely independent Custom palette.
• When HP Color: Custom is enabled, the NPC's custom palette has priority over faction colors.
• HB Linked: Same Name can synchronize the health-bar configuration of NPCs that share the exact same display name.
• NPC categories:
  • Normal
  • Elite
  • Mini-Boss
  • Boss compatibility shortcut for scripted Custom Boss Bars.
• Two visual styles:
  • Default
  • Modern
• HP text displayed directly inside the health bar.
• HP text modes:
  • Percentage
  • Current HP
  • Current / Max HP
• Customizable HP text color.
• Adjustable scale and vertical position.
• Configurable maximum render distance and distance fade.
• Smooth Damage Trail.
• Smooth Healing Animation.
• Smooth, interpolated hit flash.
• Large-damage feedback.
• Shield display with smooth delayed shield-loss trail.
• Multiple color presets and fully customizable RGB colors.
• Richer renderer-only color treatment while preserving the configured saved RGB values.

---

Styles

World / NPC Health Bars support two visual styles:

• Default — classic health-bar presentation.
• Modern — cleaner, lighter visual treatment with a compact contour and reduced heavy backing.

---

Color Customization

Health bars can have separate colors for:

• Health
• Damage Trail
• Healing
• Background
• Border
• Shield
• HP Text

Available presets include:

• Classic Green
• Crimson
• Blood
• Azure
• Arcane Purple
• Poison
• Golden
• Ice
• Dark
• Undead
• Custom RGB

HP Color Priority

Per-NPC color mode can be:

• Faction — use the NPC faction palette.
• Custom — use the NPC's own saved palette.

With Custom enabled, faction colors do not replace the NPC's Primary, Damage Trail, Healing, Background, Border, Shield, or HP Text colors.

Unrelated health-bar settings can still inherit normally from the faction.

---

HB Linked — Same Name

HB Linked can be enabled directly from the NPC display panel.

Available modes:

• Off
• Same Name

When Same Name is enabled:

• Existing NPCs in the same world with the exact same display name receive the linked health-bar configuration.
• Matching NPCs that load later can inherit the linked profile automatically.
• The linked HP palette is synchronized as Custom, using the colors from the source NPC.
• World-bar and Boss Bar configuration stored by the addon can be shared as part of the linked profile.
• Runtime combat state such as current shield absorption or current boss phase remains script/gameplay state rather than linked configuration.

This is useful for repeated enemies, guards, clones, encounter variants, or any group of NPCs that should always use the same health-bar presentation.

---

Boss Bars

The addon expands the existing CustomNPC+ Boss Bar system with both Minecraft-style and fully custom Boss Bars.

Available Boss Bar modes:

• Faction
• Hide
• Show
• Show while attacking
• Custom

Minecraft-Style Boss Bar

The original Minecraft-style Boss Bar can be recolored instead of always using purple.

Available colors include:

• Purple
• Crimson
• Green
• Blue
• Gold
• White
• Custom RGB

Custom Boss Bar

Custom Boss Bars support:

• Independent visibility modes:
  • Faction
  • Always
  • On Hit
  • On Target
  • While Attacking
• Custom width and height.
• Adjustable screen Y position.
• HP text.
• Full or compact K/M HP number formatting.
• Boss name above or below the bar.
• Smooth Damage Trail.
• Healing animation.
• Smooth hit flash and large-hit pulse.
• Shields.
• Shield layouts:
  • Off
  • Below
  • Overlay
• Boss Phases.
• Color presets and fully custom RGB colors.
• Automatic high-HP segmentation for very large health pools.
• Recent-damage position marker for clearer combat feedback.

---

Shields

NPCs and Bosses can display a secondary Shield value.

The Shield can be controlled through the scripting API, allowing creators to build their own:

• Shield absorption systems.
• Regenerating shields.
• Shield breaks.
• Temporary immunity.
• Phase-based shields.

Shield loss can also use the same smooth delayed-trail behavior as HP damage.

The addon displays Shield state; actual damage absorption remains controlled by your NPC script.

---

Boss Phases

Boss Bars can dynamically change during scripted encounters.

Boss phases can modify or display:

• Current phase.
• Total phases.
• Phase name.
• Boss Bar color.
• Shield state.
• Visual feedback.

Combine this with normal CustomNPC+ scripting to create transformations, new attacks, AI changes, and multi-stage boss fights.

---

Smooth Animations & Visual Feedback

Damage and healing transitions are evaluated using render-time interpolation instead of relying only on Minecraft's normal 20 TPS visual stepping.

Includes:

• Smooth delayed damage.
• Smooth shield-loss trail.
• Smooth healing.
• Interpolated hit flash.
• Palette-aware hit feedback.
• Healing highlight.
• Large-damage pulse.
• Recent-damage marker for Custom Boss Bars.

The HP fill also receives a renderer-only color polish so colors look richer without changing the RGB value saved in the NPC or preset.

---

Client Configuration

Additional client-side layout and renderer options are stored in:

config/CNPC-Health-Bars-Addon-client.properties

Configurable options include:

• World/NPC HP text scale.
• World/NPC HP text X/Y offsets.
• World/NPC HP text color.
• Custom Boss Bar HP text scale.
• Custom Boss Bar HP text X/Y offsets.
• Custom Boss Bar HP text color.
• Boss NPC name scale.
• Boss NPC name X/Y offsets.
• Boss NPC name color.
• Boss NPC name shadow.
• Shader Safe mode.
• High-HP segmentation enable/disable.
• HP represented per segment.
• Maximum segment count.
• Recent-damage marker enable/disable.

Existing property values are preserved when the addon rewrites or completes the config file.

---

Script API

A public scripting API is included for CustomNPC+ JavaScript / Nashorn scripts.

Recommended entry point:

var HealthBars = Java.type("com.dad.npchealthbars.api.HealthBars");

It can control:

• World-space health bars.
• Visibility.
• Categories.
• Scale and vertical position.
• Styles.
• HP text.
• Render distance and fade.
• Damage/healing feedback.
• Shields.
• Boss phases.
• Custom Boss Bars.
• Boss visibility and layout.
• Boss shield layouts.
• Per-NPC colors.
• Boss Bar colors.
• Minecraft-style Boss Bar colors.
• HB Linked / Same Name behavior.
• Reset / inheritance behavior.

Linked-profile methods include:

HealthBars.setLinkedByName(npc, true);
HealthBars.isLinkedByName(npc);
HealthBars.refreshLinked(npc);

The legacy BossBarAPI remains available for backwards compatibility with older scripts.

Full API documentation is available separately.

Click here to view the full Script API documentation

---

Performance & Compatibility

Designed with NPC-heavy maps and modded 1.7.10 clients in mind.

Features include:

• Event-fed NPC cache instead of repeatedly scanning the full loaded-entity list every few ticks.
• Cache/state cleanup when NPCs die or unload.
• Full renderer-state cleanup when changing worlds/dimensions or disconnecting.
• Distance checks and stale-NPC pruning.
• Cached configuration data.
• Reduced unnecessary rendering work.
• Shader Safe mode enabled by default.
• Opaque background behavior in Shader Safe mode.
• Strict OpenGL state isolation/restoration on guarded render paths.
• Configurable high-HP segmentation to keep large boss health pools readable.
• Multiplayer synchronization for per-NPC palettes and linked profiles.

---

Requirements

• Minecraft 1.7.10
• Minecraft Forge
• CustomNPC+

CustomNPC+ is required.

For multiplayer, server and clients should use the same addon version.

---

Credits

Created by Bacon_Saboroso.

Made as an addon for CustomNPC+.