Add comprehensive tests and documentation for passive health regeneration behavior

src/config/config.py

@@ -9,8 +9,10 @@ def __init__(self):
         self.godMode = False  # Disable god mode
         self.maxTicks = 1000
         self.tickLength = 0.1
-        
+
         # Early-game survival settings
         self.earlyGameGracePeriod = 50  # Number of ticks of protection for player
-        self.playerDamageReduction = 0.4  # 40% damage reduction for player during grace period
+        self.playerDamageReduction = (
+            0.4  # 40% damage reduction for player during grace period
+        )
         # During grace period, other creatures have 85% chance to avoid attacking player

src/entity/livingEntity.py

@@ -58,10 +58,13 @@ def fight(self, kreature):
             if self.health > 0:
                 damage = random.randint(15, 25)  # Random damage between 15-25
                 # Apply damage reduction if target has it
-                if hasattr(kreature, 'damageReduction') and kreature.damageReduction > 0:
+                if (
+                    hasattr(kreature, "damageReduction")
+                    and kreature.damageReduction > 0
+                ):
                     damage = int(damage * (1 - kreature.damageReduction))
                     damage = max(damage, 1)  # Ensure at least 1 damage
-                
+
                 kreature.health -= damage
                 if kreature.health <= 0:
                     self.log.append(
@@ -86,10 +89,10 @@ def fight(self, kreature):
             if kreature.health > 0:
                 damage = random.randint(15, 25)  # Random damage between 15-25
                 # Apply damage reduction if target has it
-                if hasattr(self, 'damageReduction') and self.damageReduction > 0:
+                if hasattr(self, "damageReduction") and self.damageReduction > 0:
                     damage = int(damage * (1 - self.damageReduction))
                     damage = max(damage, 1)  # Ensure at least 1 damage
-                
+
                 self.health -= damage
                 if self.health <= 0:
                     kreature.log.append(
@@ -151,7 +154,13 @@ def isAlive(self):
         return self.health > 0
 
     def regenerateHealth(self):
-        """Regenerate a small amount of health over time"""
+        """Regenerate a small amount of health over time
+
+        This is a passive background process that does not interfere with entity actions.
+        Entities continue making decisions (fighting, befriending, reproducing) regardless
+        of their health status or regeneration state. This method is called separately from
+        getNextAction() to ensure regeneration happens alongside normal entity behavior.
+        """
         if (
             self.health < self.maxHealth and random.randint(1, 10) <= 3
         ):  # 30% chance per tick

src/kreatures.py

@@ -22,10 +22,12 @@ def __init__(self):
         self.running = True
         self.config = Config()
         self.tick = 0
-        
+
         # Initialize player early-game protection
         self.playerCreature.damageReduction = self.config.playerDamageReduction
-        self.playerCreature.log.append("%s has early-game protection!" % self.playerCreature.name)
+        self.playerCreature.log.append(
+            "%s has early-game protection!" % self.playerCreature.name
+        )
 
     def _load_names(self):
         """Load names from configuration file"""
@@ -85,13 +87,15 @@ def initiateEntityActions(self):
                     if self.config.godMode:
                         continue
                     # During grace period, 85% chance to skip attacking the player
-                    if (self.tick < self.config.earlyGameGracePeriod and 
-                        random.randint(1, 100) <= 85):
+                    if (
+                        self.tick < self.config.earlyGameGracePeriod
+                        and random.randint(1, 100) <= 85
+                    ):
                         entity.log.append(
                             "%s decided not to attack %s." % (entity.name, target.name)
                         )
                         continue
-                
+
                 entity.increaseChanceToFight()
                 entity.decreaseChanceToBefriend()
                 entity.fight(target)
@@ -113,12 +117,24 @@ def updatePlayerProtection(self):
         """Update player protection based on current tick"""
         if self.tick >= self.config.earlyGameGracePeriod:
             # Grace period has ended
-            if hasattr(self.playerCreature, 'damageReduction') and self.playerCreature.damageReduction > 0:
+            if (
+                hasattr(self.playerCreature, "damageReduction")
+                and self.playerCreature.damageReduction > 0
+            ):
                 self.playerCreature.damageReduction = 0
-                self.playerCreature.log.append("%s's protection has worn off!" % self.playerCreature.name)
+                self.playerCreature.log.append(
+                    "%s's protection has worn off!" % self.playerCreature.name
+                )
 
     def regenerateAllEntities(self):
-        """Regenerate health for all living entities"""
+        """Regenerate health for all living entities
+
+        This method is called every game tick AFTER entities take their actions in
+        initiateEntityActions(). Health regeneration is a passive background process
+        that does not prevent entities from making decisions or taking actions.
+        Entities continue to fight, befriend, and reproduce regardless of their
+        health status or whether they are regenerating.
+        """
         for entity in self.environment.getEntities():
             if entity.isAlive():
                 entity.regenerateHealth()
@@ -225,12 +241,18 @@ def printSummary(self):
             "%s's chance to be nice was %d percent."
             % (self.playerCreature.name, self.playerCreature.chanceToBefriend)
         )
-        
+
         # Show protection status
-        if hasattr(self.playerCreature, 'damageReduction') and self.playerCreature.damageReduction > 0:
+        if (
+            hasattr(self.playerCreature, "damageReduction")
+            and self.playerCreature.damageReduction > 0
+        ):
             protection_percent = int(self.playerCreature.damageReduction * 100)
-            print("%s still has %d%% damage reduction." % (self.playerCreature.name, protection_percent))
-
+            print(
+                "%s still has %d%% damage reduction."
+                % (self.playerCreature.name, protection_percent)
+            )
+
         if self.playerCreature.isAlive():
             print(
                 "%s ended with %d health (out of %d max)."
@@ -269,9 +291,14 @@ def run(self):
             except:  # if list is empty, just keep going
                 pass
 
+            # Game tick order is important:
+            # 1. Entities take actions (fight, befriend, reproduce) based on their decision-making
             self.initiateEntityActions()
-            self.updatePlayerProtection()  # Update player protection status
-            self.regenerateAllEntities()  # Regenerate health for all entities
+            # 2. Update player protection status based on current tick
+            self.updatePlayerProtection()
+            # 3. Passive health regeneration happens AFTER actions, as a background process
+            #    This ensures entities can take actions regardless of health/regeneration status
+            self.regenerateAllEntities()
             time.sleep(self.config.tickLength)
             self.tick += 1
             if self.tick >= self.config.maxTicks: