2

Description

"A simple Node based approach to composition of health. When attached to a parent node you will grant it health related functions and let it micro manage the small details, such as clamping and detecting death. Combined with Signals you can easily get relevant information from the component without calling it from a process function.\r\n\r\n\r\nOn Github, you can grab a project with a basic UI setup to control and exercise almost all functions you would typically use in your own.\r\n\r\nIf you're new to Composition, I suggest watching these excellent videos on the subject.\r\n- [youtube: How You Can Easily Make Your Code Simpler in Godot 4](https:\/\/www.youtube.com\/watch?v=74y6zWZfQKk){ data-author=\"Bitlytic\" }\r\n- [youtube: Using Composition to Make More Scalable Games in Godot](https:\/\/www.youtube.com\/watch?v=rCu8vQrdDDI){ data-author=\"Firebelly Games\" }\r\n- [youtube: Godot Components - how to structure a game into manageable parts (Beginner\/Intermediate)](https:\/\/youtu.be\/W8gYHTjDCic){ data-author=\"Godotneers\" }\r\n\r\n## What it does\r\n- Manages Health\r\n\t- Clamping to 0, or Max Health\r\n\t\t- Toggle to allow exceeding maximum health\r\n- Emits several signals\r\n\t- damaged(), When taking damage with an amount\r\n\t- healed() When taking healing with an amount\r\n\t- died(), When current health <= 0, with an Overkill amount\r\n\t- resurrected() When current health was 0, but is now >= 1\r\n\t- health_changed() When any change to current or max health happens\r\n\t\t- Used for Health Bars \/ Labels\r\n- Healing the difference on max health change.\r\n- Disallow Healing if Dead\r\n- Disallow Resurrection if not Dead\r\n- God Mode (Prevents all but forced damage)\r\n- Provides methods to force damage and healing for scripted events.\r\n\r\n## What it doesn't\r\n- Regeneration\r\n- Mitigation (Armor, Resistance, Dodge, etc)\r\n- Audio\/Visual\/Animations\r\n- Serialization (See [Node vs Resource](#node-vs-resource))\r\n- queue_free()\r\n\r\n## Node vs Resource{#node-vs-resource}\r\n\r\nIn Godot, using a Node is \"costly\" (in relevant terms) compared to an Object\/RefCounted. It also offers no serialization compared to a Resource.\r\n\r\nThe primary reason this component is a Node is for ease of use. It allows you to add it to script or node with a simple `@onready var health_component: HealthComponent = $HealthComponent` or exported property. It also allows easy connection of signals in editor.\r\n\r\nLastly, the health component can be used for a lot of different projects and entities. You don't necessarily need to serialize the health of a choppable tree, or a rodent enemy of Arena Survival game.\r\n\r\nIf you need to optimize further, you should be proficient enough to remove the @exports and change it to a RefCounted type, and add an _init() function.\r\n\r\n## Credits\r\n\r\nPixel-Boy for his Godot Node Icons: https:\/\/pixel-boy.itch.io\/icon-godot-node"

Main code

# Health Component by Zaura
# Version 1.0
# Github: https://github.com/ZauraGS
# BlueSky: https://bsky.app/profile/zaura-dev.bsky.social

@icon("./icon_heart.png")
class_name HealthComponent extends Node

enum TYPE { DAMAGE, HEALING, RESURRECTION }

## The Health Component is used to give any node it's attached to health related functions.
##
## This component offers a variety of functions that can be personalized for each instance, including clamping [member current_health] values, ignoring all damage taken,
## exceeding [member max_health], and automatically emitting signals for damaging and healing events.[br][br]
##
## There are three primary methods for interacting with health.[br]
## [method take_damage][br]
## [method take_healing][br]
## [method resurrect][br][br]
## Another two methods are also provided to forcibly cause damage and healing which [u]can[/u] ignore [member god_mode], primarily used for scripting interactions.[br]
## [method force_damage][br]
## [method force_heal][br][br]

signal health_changed(current_amount: int, max_amount: int) ## Emitted every time [member current_health] is changed in a neutral context, should be used with interface functions
signal damaged(amount: int) ## Emitted when [member current_health] is changed in a negative context.
signal healed(amount: int) ## Emitted when [member current_health] is changed in a postive context.
signal resurrected ## Emitted when [member current_health] was at 0, and now is positive.
signal died(overkill: int) ## Emitted when [member current_health] has reached 0.

@export var max_health: int = 10: ## The maximum amount of [member current_health] this component can have normally. By default on creation current [member current_health] will be set to this value.
	set(value):
		var previous: int = max_health
		max_health = value
		if heal_difference:
			current_health += max_health - previous
		current_health = clamp(current_health, 0, max_health)
		health_changed.emit(current_health, max_health)

@export var exceed_maximum_health: bool = false ## Allows current [member current_health] to exceed [member max_health], used in niche situations.
@export var heal_difference: bool = true ## When modifying [member max_health] if it should grant the [member current_health] gained from [member max_health] increasing.
@export var god_mode: bool = false ## Causes all damage to be ignored unless forced by [method force_damage]. This does not stop healing from occuring.

var current_health: int = max_health: ## The current health, Will clamp any value changes to 0 or [member max_health] unless [member exceed_maximum_health] is enabled.
	set(value):
		if exceed_maximum_health:
			current_health = max(0, value)
		else:
			current_health = clamp(value, 0, max_health)
		health_changed.emit(current_health, max_health)
var dead: bool = false ## Used for resurrection purposes.

#region Public Functions

## The Public Method to negatively effect [member current_health].
func take_damage(damage: int) -> void:
	_change_health(damage, TYPE.DAMAGE)

## The Public Method to postively effect [member current_health].
func take_healing(healing: int) -> void:
	_change_health(healing, TYPE.HEALING)

## The Public Method to resurrect if [member dead].
func resurrect(healing: int) -> void:
	_change_health(healing, TYPE.RESURRECTION)

#endregion

#region Private Functions

## The Private method to effect the [member current_health] of the component.[br][br]
## Expected Operations:[br]
## 1. You can always be healed unless [member dead].[br]
## 2. You can only be resurrected when [member dead].[br]
## 3. If [member god_mode] is enabled, exit early.[br]
## 4. Lastly if [member current_health] is equal to 0, [signal died] will be emitted with overkilled amount.[br]
func _change_health(amount: int, type: TYPE) -> void:
	match type:
		TYPE.HEALING:
			if dead:
				return
			current_health += amount
			healed.emit(amount)
		TYPE.RESURRECTION:
			if not dead:
				return
			dead = false
			current_health += amount
			healed.emit(amount)
			resurrected.emit()
		TYPE.DAMAGE:
			if god_mode:
				return
			var overkill: int = amount - current_health
			current_health -= amount
			damaged.emit(amount)
			if current_health <= 0:
				dead = true
				died.emit(overkill)

#endregion

#region Force Methods

## This method will forcibly cause damage, and can be set to not ignore [member god_mode].[br]
## [u]This is not the intended way to cause damage or healing and shoud be used only for scripting scenarios.[/u]
func force_damage(amount: int, ignore_god_mode: bool = true) -> void:
	var current_god_status: bool = god_mode
	if ignore_god_mode:
		god_mode = false
	_change_health(amount, TYPE.DAMAGE)
	god_mode = current_god_status

## This method will forcibly increase [member current_health] and cause resurrection to happen.[br]
## [u]This is not the intended way to cause damage or healing and shoud be used only for scripting scenarios.[/u]
func force_heal(amount: int) -> void:
	if dead:
		_change_health(amount, TYPE.RESURRECTION)
	else:
		_change_health(amount, TYPE.HEALING)

#endregion

Comments