add show_health_bar attribute to toggle health bar visibility

[anasdhaoidi]

show_health_bar — Shield Node Attribute

Overview

show_health_bar is an int attribute on the shield node that controls
when the health bar is rendered above a shield.

Default value: 1 (briefly)

---

Values

Value	Behavior
0	Bar is never rendered, regardless of damage.
1	Bar appears for 2 seconds after the shield takes damage, then fades out. (default)
2	Bar is always visible, with a minimum opacity so it never fully fades.

---

Usage

import bascenev1 as bs

# 0 — disabled: bar is permanently hidden
shield_hidden = bs.newnode('shield', attrs={
    'position': [0.0, 1.5, 0.0],
    'radius': 1.2,
    'color': [0.3, 0.6, 1.0],
    'hurt': 0.0,
    'show_health_bar': 0,
})

# 1 — briefly (default): bar fades in on hit, gone after 2 seconds
shield = bs.newnode('shield', attrs={
    'position': [0.0, 1.5, 0.0],
    'radius': 1.2,
    'color': [0.6, 0.4, 0.1],
    'hurt': 0.0,
    'show_health_bar': 1,
})

# 2 — always: bar stays visible at all times
shield_always = bs.newnode('shield', attrs={
    'position': [0.0, 1.5, 0.0],
    'radius': 1.2,
    'color': [0.3, 0.8, 0.3],
    'hurt': 0.0,
    'show_health_bar': 2,
})

# Can also be changed at runtime
shield.show_health_bar = 0  # hide the bar mid-game
shield.show_health_bar = 1  # restore default behavior

---

Why This Attribute Matters

1. Visual-only shields

Some mods use the shield node purely as a visual effect — a glow around a character,
an environmental aura, or a decorative ring. In these cases the health bar is meaningless
noise that breaks the visual presentation. show_health_bar = 0 removes it cleanly
without touching any other shield behavior.

2. Intentional information hiding

In mods, a designer may want certain shields to be secret — hidden
from the player entirely. Before this attribute, the health bar would always betray the
shield's presence the moment it took damage. Now it can remain invisible even under fire.

3. Completing the control surface

Before this addition, the engine only offered two states via always_show_health_bar:

• Show bar for 2 seconds after a hit
• Show bar always

There was no way to say never show. show_health_bar fills that gap and gives mod
authors full, explicit control over health bar visibility with a single attribute.

4. Runtime flexibility

Because it is a proper node attribute, it can be toggled at any point during gameplay —
useful for mechanics where a shield becomes "revealed" under specific conditions, or
where UI visibility changes based on game state.

---

Changes from Previous Design

The original implementation used two separate bool attributes:

Old	Type	Role
always_show_health_bar	bool	Show bar permanently
show_health_bar	bool	Toggle bar on/off

This created an ambiguous fourth case: what happens when
show_health_bar = False and always_show_health_bar = True?
Does always win or does never win? The behavior was undefined
and unintuitive for modders.

The new show_health_bar int attribute replaces both with a single
enum-style value — every combination is explicitly defined, nothing
is ambiguous:

Old (always / show)	New (show_health_bar)
False / False	0 (disabled)
False / True	1 (briefly, default)
True / True	2 (always)
True / False	❌ undefined → eliminated

---

Implementation Notes

Registered via BA_INT_ATTR_LATE in ShieldNodeType and evaluated in
ShieldNode::Draw() using an internal HealthBarMode enum:

enum class HealthBarMode { kDisabled = 0, kBriefly = 1, kAlways = 2 };

if (health_bar_mode_ != HealthBarMode::kDisabled
    && (since_last_hurt_change < fade_time
        || health_bar_mode_ == HealthBarMode::kAlways)) {
    // health bar drawing code
}

The default value kBriefly (1) preserves original engine behavior —
no existing mods are affected unless they explicitly set show_health_bar.

[Loup-Garou911XD]

One design note, i think u should use enum for this instead of 2 bool, your table doesn't cover the fourth case where show_health_bar is false and always_show_health_bar is true.What would we do in this condition?
So it is unintuitive imo

Instead enums like always, briefly, never makes more sense to me

And if you do end up implementing that, pls add that to the python docs because modders would definitely have a hard time looking that up in cpp code

[Loup-Garou911XD]

the ci is failing because of `BA_INT_ATTR_LATE` i think

[Loup-Garou911XD]

Also would be nice if you added python documentation for the sheild