From de067595141aebe40d4e4486c16a34e91e4b6409 Mon Sep 17 00:00:00 2001
From: RealMelwei <melvin@weissprivat.de>
Date: Wed, 15 Oct 2025 16:00:47 +0200
Subject: [PATCH] Refactored and documented utils

---
 utils/earth_aligner.gd     | 17 ++++++++++-------
 utils/enemy_hurtbox.gd     | 30 +++++++++++++++++++-----------
 utils/enemy_hurtbox.tscn   |  6 ++++++
 utils/global.gd            |  2 ++
 utils/interactable_area.gd |  1 +
 utils/platform.gd          |  3 +++
 6 files changed, 41 insertions(+), 18 deletions(-)

diff --git a/utils/earth_aligner.gd b/utils/earth_aligner.gd
index 74e4e40..fb3f54a 100644
--- a/utils/earth_aligner.gd
+++ b/utils/earth_aligner.gd
@@ -1,8 +1,9 @@
 extends Node2D
 
-var parent : Node2D
 @export var center = Vector2.ZERO
 var angle = 0
+
+# Quick access to relative cardinal directions
 var up : Vector2 :
 	get():
 		return global_from_local(Vector2.UP)
@@ -17,18 +18,20 @@ var left : Vector2 :
 		return global_from_local(Vector2.LEFT)
 
 func _ready() -> void:
-	parent = get_parent()
 	align()
 
 func _process(_delta: float) -> void:
 	align()
-	
-func align():
-	angle = -(parent.position - center).angle_to(Vector2.UP)
-	parent.rotation = angle;
 
+# Aligns the parent to the center
+func align():
+	angle = -(get_parent().position - center).angle_to(Vector2.UP)
+	get_parent().rotation = angle;
+
+# Converts directions in local coordinates into global coordinates
 func global_from_local (_velocity: Vector2) -> Vector2:
 	return _velocity.rotated(angle)
-	
+
+# Converts directions in global coordinates into local coordinates
 func local_from_global (_velocity: Vector2) -> Vector2:
 	return _velocity.rotated(-angle)
diff --git a/utils/enemy_hurtbox.gd b/utils/enemy_hurtbox.gd
index 134b2c0..da8ec37 100644
--- a/utils/enemy_hurtbox.gd
+++ b/utils/enemy_hurtbox.gd
@@ -1,43 +1,51 @@
 class_name EnemyHurtbox extends Area2D
 
+# HP Management
 @export var max_hp : int
-@onready var hp = max_hp
+@onready var hp = max_hp :
+	set(new_hp):
+		if new_hp > max_hp:
+			new_hp = max_hp
+		if new_hp < 0 :
+			new_hp = 0
+		hp = new_hp
+		if hp == 0:
+			die()
 @export var flash_duration = 0.2
 @export var canvasItem : CanvasItem
 @export var flashColor : Color = Color(1.5, 1.5, 1.5)
+
+# Instance-Specific Damage Cooldown
 @export var id_block_time = 0.12
-var flash_time = 0
 var blocked_damage_ids : Array[int] = []
 
 signal damage_taken(damage, dir, id)
 signal died
 
-func _process(delta: float) -> void:
-	flash_time = max(flash_time-delta, 0)
-	if(flash_time <= 0 and canvasItem != null):
+# Reset Hit Flash
+func _on_flash_ended():
+	if canvasItem != null:
 		canvasItem.modulate = Color(1,1,1)
 
 func hurt(damage : int, dir : Vector2 = Vector2.ZERO, id : int = -1) -> bool:
 	if not id in blocked_damage_ids:
 		block_id(id)
 		if canvasItem != null: canvasItem.modulate = flashColor
-		flash_time = flash_duration
-		hp = max(hp-damage, 0)
+		$FlashTimer.start(flash_duration)
+		hp -= damage
 		damage_taken.emit(damage, dir, id)
-		if(hp <= 0):
-			die()
 		return true
 	return false
 
+# When taking damage, prevent damage from that instance for id_block_time.
 func block_id(id : int):
 	blocked_damage_ids.append(id)
 	await get_tree().create_timer(id_block_time).timeout
 	var id_pos = blocked_damage_ids.find(id)
 	if not id_pos == -1: blocked_damage_ids.remove_at(id_pos)
 
-
 func die():
 	died.emit()
 
 func destroy():
-	hurt(9999)
+	hurt(10 * max_hp)
diff --git a/utils/enemy_hurtbox.tscn b/utils/enemy_hurtbox.tscn
index a17c190..dc85322 100644
--- a/utils/enemy_hurtbox.tscn
+++ b/utils/enemy_hurtbox.tscn
@@ -5,3 +5,9 @@
 [node name="EnemyHurtbox" type="Area2D"]
 collision_layer = 18
 script = ExtResource("1_wa58b")
+
+[node name="FlashTimer" type="Timer" parent="."]
+wait_time = 0.2
+one_shot = true
+
+[connection signal="timeout" from="FlashTimer" to="." method="_on_flash_ended"]
diff --git a/utils/global.gd b/utils/global.gd
index 98c6a61..a74e000 100644
--- a/utils/global.gd
+++ b/utils/global.gd
@@ -1,9 +1,11 @@
 class_name Global
 
+# Returns the next damage instance (and increases by 1)
 static var next_dmg_id : int = 0 : 
 	get:
 		next_dmg_id += 1
 		return next_dmg_id
 
+# Entrywise modulo
 static func vec_mod(vec : Vector2, modulus : float):
 	return Vector2(fposmod(vec.x, modulus), fposmod(vec.y, modulus))
diff --git a/utils/interactable_area.gd b/utils/interactable_area.gd
index 02e7896..2a5a3ef 100644
--- a/utils/interactable_area.gd
+++ b/utils/interactable_area.gd
@@ -1,3 +1,4 @@
+# Simple area that emits a signal when the player interacts while overlapping
 extends Area2D
 
 @export var oneshot = true
diff --git a/utils/platform.gd b/utils/platform.gd
index ee867da..dd1b435 100644
--- a/utils/platform.gd
+++ b/utils/platform.gd
@@ -2,12 +2,15 @@ class_name Platform extends StaticBody2D
 var building
 
 func _ready() -> void:
+	# Choose a platform design at random
 	if(randf() > 0.5):
 		$Sprite2D.visible = true
 		$Sprite2D2.visible = false
 
+# Stretch platforms depending on their height to prevent gaps in the ceiling
 func init_at_horizontal_distortion(distortion : float):
 	scale.x *= distortion
 
+# When a platform is destroyed, destroy the whole building
 func destroy():
 	building.destroy()