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.
- Requirements
- ✨Installation
- Getting Started
- Examples
- Exported parameters
- Accessible normal variables
- Functionality
- 💛Invulnerability
- 😵When health reachs zero
- ➗Percentage of actual health
- 📊Multiple health bars
- 📶Signals
- ✌️You are welcome to
- 🤝Contribution guidelines
- 📇Contact us
📢 We don't currently give support to Godot 3+ as we focus on future stable versions from version 4 onwards
- Godot 4.0+
You can download this plugin from the official Godot asset library using the AssetLib tab in your godot editor. Once installed, you're ready to get started
To manually install the plugin, create an "addons" folder at the root of your Godot project and then download the contents from the "addons" folder of this repository
This plugin has also been written in C# and you can find it on HealthComponentCSharp
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.
When this component becomes ready in the scene tree, a series of steps are carried out:
- Ensure that the current health does not exceed the maximum health.
- Set up the health regeneration timer.
- Set up the invulnerability timer.
- If the health regeneration per second exceeds zero, activate health regeneration.
- Establish a connection to its own
health_changedsignal. Whenever the health changes, this signal is triggered. If health regeneration is enabled, it is also triggered, and if the current health reaches zero, adiedsignal is emitted. - Establish a connection to its own
diedsignal. Once this signal is emitted, the built-in timers within the component are halted.
We usually have an examples folder in our repositories to showcase how to use the plugin in a specific context.
In this case we have a available a simple progress bar that is monitoring the health component to update every time a change happen:
- Max health (its maximum achievable health)
- Health overflow percentage (health percentage that can be surpassed when life-enhancing methods such as healing or shielding are used)
- Current Health (the actual health of the node)
- Health regen (The amount of health regenerated each tick)
- Health regen tick time (tick time defined where the health regen is applied)
- Is Invulnerable (the invulnerability flag, when is true no damage is received but can be healed)
- Invulnerability time (how long the invulnerability will last, set this value as zero to be an indefinite period)
- max_health_overflow
- enum TYPES {HEALTH, REGEN, DAMAGE}
- invulnerability_timer
- health_regen_timer
The max_health_overflow is a computed 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
You have a maximum normal health of 120 but can be surpassed a 15% so our new limit is 138. This can be useful to implement shield mechanics where you need to separate this type of health.
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.
@onready var health_component = $HealthComponent as GodotParadiseHealthComponent
health_component.damage(10)
health_component.damage(99)
# Parameter is treated as absolute value
health_component.damage(-50) # translate to 50 inside the functionThe 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.
@onready var health_component = $HealthComponent as GodotParadiseHealthComponent
health_component.health(25)
# Parameter is treated as absolute value
health_component.health(-50)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:
@onready var health_component = $HealthComponent as GodotParadiseHealthComponent
health_component.enable_health_regen(10)
# or disable it
health_component.enable_health_regen(0)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:
@onready var health_component = $HealthComponent as GodotParadiseHealthComponent
health_component.enable_invulnerability(true, 2.5)
# You can deactivating it manually with
health_component.enable_invulnerability(false)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
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.
@onready var health_component = $HealthComponent as GodotParadiseHealthComponent
var is_dead: bool = health_component.check_is_death()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.
To achieve this mechanic you can simple add multiple health components as childs on the target node and create a basic chain responsibility logic using the died signal. This is a very basic example and we recommend that you adapt it to your needs if they are a little more complex, we just want to give you a basic idea.
@onready var health_component = $HealthComponent as GodotParadiseHealthComponent
@onready var health_component2 = $HealthComponent2 as GodotParadiseHealthComponent
@onready var health_component3 = $HealthComponent3 as GodotParadiseHealthComponent
var life_bars := [health_component, health_component2, health_component3]
func _ready():
life_bars.back().died.connect(on_life_bar_consumed)
func on_life_bar_consumed():
var last_life_bar = life_bars.pop_back()
last_life_bar.died.disconnect(on_life_bar_consumed)
if life_bars.size() > 0:
life_bars.back().died.connect(on_life_bar_consumed)
## Continue the logic...###
# 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 diedGodotParadise is available for free.
If you're grateful for what we're doing, please consider a donation. Developing GodotParadise requires massive amount of time and knowledge, especially when it comes to Godot. Even $1 is highly appreciated and shows that you care. Thank you!
Thank you for your interest in Godot Paradise! To ensure a smooth and collaborative contribution process, please review our contribution guidelines before getting started. These guidelines outline the standards and expectations we uphold in this project.
📓Code of Conduct: We strictly adhere to the Godot code of conduct in this project. As a contributor, it is important to respect and follow this code to maintain a positive and inclusive community.
If you have built a project, demo, script or example with this plugin let us know and we can publish it here in the repository to help us to improve and to know that what we do is useful.