💓Health Component

Effortlessly simulate health and damage for entities within your video game.

This component handles all aspects related to taking damage and managing health on the parent node. While typically added to a CharacterBody2D, there are no limitations preventing its use with a StaticRigidBody2D, allowing you to imbue life into objects like trees or other in-game elements.

Setup

Incorporate this component as a child node in the location where you intend to implement life and damage mechanics. Simply define the initial values you wish to assign to this component.

Exported values

• Max health

• Health overflow percentage

• Current Health

• Health regen per second

• Is Invulnerable (The invulnerability flag, when is true no damage is received but can be healed)

• Invulnerability time

Accessible normal variables

• max_health_overflow

• enum TYPES {HEALTH, REGEN, DAMAGE}

• invulnerability_timer

• health_regen_timer

The Max health overflow is a calculated variable that represents the sum of the maximum health and the applied health overflow percentage.

Example: max_health of 120 and health overflow percentage of 15% = 138

Ready

When this component becomes ready in the scene tree, a series of steps are carried out:

1. Ensure that the current health does not exceed the maximum health.

2. Establish the health regeneration timer.

3. Set up the invulnerability timer.

4. If the health regeneration per second exceeds zero, activate health regeneration.

5. Establish a connection to its own health_changed signal. Whenever the health changes, this signal is triggered. If health regeneration is enabled, it is also triggered, and if the current health reaches zero, a died signal is emitted.

6. Establish a connection to its own died signal. Once this signal is emitted, the built-in timers within the component are halted.

Taking damage

To subtract a specific amount of health, you can effortlessly invoke the damage() function within the component.

This triggers the emission of a health_changed signal each time damage is inflicted. Moreover, the component constantly monitors if the current health has plummeted to zero, subsequently triggering a died signal.

It's worth noting that the component is autonomously connected to its own died signal, concurrently ceasing the health_regen_timer and invulnerability_timer. If the is_invulnerable variable is set to true, any incoming damage, regardless of its magnitude, will be disregarded. Nevertheless, the standard signal broadcasting will persist as expected..

health_component.damage(10)
health_component.damage(99)

# Parameter is treated as absolute value
health_component.damage(-50) # translate to 50 inside the function

Healing

The functionality mirrors that of the damage function, but in this instance, health is added to the component. It's important to note that the healing process can never surpass the predetermined max_health_overflow. Following each execution of the health function, a health_changed signal is emitted.

health_component.health(25)

# Parameter is treated as absolute value
health_component.health(-50)

Health regeneration per second

By default, health regeneration occurs every second. When the health component invokes the damage() function, regeneration is activated until the maximum health is reached, at which point it deactivates.

You have the flexibility to dynamically adjust the rate of regeneration per second using the enable_health_regen function. Alternatively, you can set it to zero to disable health regeneration altogether:

health_component.enable_health_regen(10)
# or disable it
health_component.enable_health_regen(0)

Invulnerability

You have the ability to toggle invulnerability on or off through the enable_invulnerability function. By providing the enable parameter (a boolean), you can specify whether invulnerability is activated or not. Additionally, you can set a time duration (in seconds) during which the entity will be invulnerable. Once the specified time limit is reached, invulnerability will be deactivated:

health_component.enable_invulnerability(true, 2.5)

# You can deactivating it manually with
health_component.enable_invulnerability(false)

When health reachs zero

This component solely emits a "died" signal, offering you the flexibility to tailor the behavior to your game's needs. By establishing a connection to this signal, you can trigger animations, function calls, collect statistics, and perform other relevant actions to customize the experience according to your game's requirements..

Death manual check

Perform a manual check to ascertain if the entity has entered the death state. If you wish to manually determine this state, you can utilize the check_is_death function. This function emits the died signal if the current health reaches zero.

var is_dead: bool = health_component.check_is_death()

Percentage of actual health

If you intend to exhibit a health bar UI, you can access the health percentage format through the get_health_percent() function. This function returns a dictionary structured as follows:

# For instance, if 80% of the maximum health represents the current health:

{
   "current_health_percentage": 0.8,
   "overflow_health_percentage": 0.0,
   "overflow_health": 0
}

# Similarly, considering a maximum health of 100, a health overflow percentage of 20.0, and a current health of 120:

{ "current_health_percentage": 1.0,
   "overflow_health_percentage": 0.2,
   "overflow_health": 20
}

This information can aid in accurately representing the health status and overflow in a visual health bar.

Signals

### 
# You can access the action type in the health_changed signal
# to determine what kind of action was taken and act accordingly to the flow of your game.
###

enum TYPES {
	DAMAGE,
	HEALTH,
	REGEN
}

signal health_changed(amount: int, type: TYPES)
signal invulnerability_changed(active: bool)
signal died