From 96b12b9dea84de1540883bfeaae10c6c7cd578cc Mon Sep 17 00:00:00 2001
From: EmptyStar <gitmail@emptystar.email>
Date: Wed, 16 Apr 2025 12:24:11 -0500
Subject: [PATCH] Add immortal and fall_damage_add_percent armor groups (#3)

This change adds special handling for these armor groups, ensuring that their default values will remain as they are while also allowing mods to manage these groups via Armor Monoid.
Beware that the value range does not exactly correspond to the Luanti-provided API.
---
 README.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 init.lua  | 15 ++++++++++++++-
 2 files changed, 64 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 8542690..9466b4e 100644
--- a/README.md
+++ b/README.md
@@ -28,4 +28,53 @@ armor_monoid.register_armor_group("arcane", 100)
 <br/>
 As you can see, the argument is not a multiplier, but the base armor group
 rating. Calling this would mean players start off with an armor rating in
-"arcane" of 100 (no protection).
\ No newline at end of file
+"arcane" of 100 (no protection).
+
+Special armor groups
+====================
+
+Luanti defines a number of [special armor groups](https://github.com/luanti-org/luanti/blob/master/doc/lua_api.md#objectref-armor-groups)
+that have an engine-based effect and therefore must be handled uniquely by this
+monoid.
+
+`fall_damage_add_percent`
+-------------------------
+
+The `fall_damage_add_percent` armor group controls how much additional damage
+that a player will incur when falling from a high height. The armor monoid
+handles this group exactly like normal armor groups that have a base value of
+100.
+
+The armor monoid uses the following range of values for the
+`fall_damage_add_percent` armor group:
+
+- `value = 100`: player takes normal fall damage (100%)
+- `value = 0`: player takes no fall damage (0%)
+- `value = X`: player takes X% less fall damage (1%-99%)
+- default value: 100
+
+To grant a player fall damage reduction, use the `fall_damage_add_percent` group
+as you would any normal armor group:
+
+```lua
+armor_monoid.monoid:add_change(player,{fall_damage_add_percent=0.5},"mymod:half_fall_damage")
+```
+
+`immortal`
+----------
+
+The `immortal` armor group controls whether or not a player can suffer damage
+and experience drowning. Due to limitations of this monoid, the values of this
+armor group are handled differently than most armor groups.
+
+The armor monoid uses the following values for the `immortal` armor group:
+
+- `value <= 1`: player is not immortal, subject to damage and drowning
+- `value > 1`: player is immortal, will not suffer damage and cannot drown
+- default value: 1
+
+To grant a player immortality, set this group to a value greater than 1 like so:
+
+```lua
+armor_monoid.monoid:add_change(player,{immortal=2},"mymod:immortality")
+```
\ No newline at end of file
diff --git a/init.lua b/init.lua
index 3a0d0ca..a600fc7 100644
--- a/init.lua
+++ b/init.lua
@@ -1,7 +1,11 @@
 
 armor_monoid = {}
 
-local armor_groups = { fleshy = 100 }
+local armor_groups = {
+	fleshy = 100,
+	fall_damage_add_percent = 100,
+	immortal = 1,
+}
 
 armor_monoid.registered_groups = armor_groups
 
@@ -71,6 +75,15 @@ armor_monoid.monoid = player_monoids.make_monoid({
 			end
 		end
 
+		-- fall_damage_add_percent is a special armor group that has an inherent
+		-- value of 0 rather than 100, so its final value is offset by -100 here
+		final.fall_damage_add_percent = final.fall_damage_add_percent - 100
+
+		-- immortal is a special armor group that must be either 0 or 1 to indicate
+		-- mortality or immortality, respectively, so its final value is constrained
+		-- here
+		final.immortal = final.immortal > 1 and 1 or 0
+
 		join_handled[player:get_player_name()] = true
 
 		player:set_armor_groups(final)