Enhance EntityAnim class with loop control and restart functionality

Author: Natuworkguy

engine/core/__init__.py

@@ -13,7 +13,6 @@
 import pygame
 import importlib.util
 import sys
-import tkinter.messagebox
 import uuid
 import os
 import colorama
@@ -98,10 +97,8 @@ def __init__(
                     self.image = EntityImage(image)
                 else:
                     self.image = EntityAnim(image)
-            except pygame.error as e:
+            except (pygame.error, FileNotFoundError) as e:
                 logger(f"Failed to load image or animation '{image}': {str(e)}", status=LoggerStatus.WARNING)
-            except FileNotFoundError as e:
-                tkinter.messagebox.showerror("File not found", str(e))
 
         if scriptfile is not None:
             esfid = f"esf-{self.id}"
@@ -120,12 +117,12 @@ def __init__(
                     try:
                         spec.loader.exec_module(self.scriptfile_module)
                     except FileNotFoundError:
-                        tkinter.messagebox.showerror(
-                            "Error",
+                        logger(
                             f'Script file "{scriptfile}" not found. Please ensure the file exists and try again.',
+                            status=LoggerStatus.CRITICAL,
                         )
                     except ImportError as e:
-                        tkinter.messagebox.showerror("Error", f"Error when loading script: {e}")
+                        logger(f"Error when loading script: {e}", status=LoggerStatus.CRITICAL)
 
             if self.scriptfile_module is not None:
                 if self.scriptfile is not None:

engine/core/animation.py

@@ -20,19 +20,27 @@ class EntityAnim:
     entity holding one needs no special handling, and frames advance off the
     clock on their own: drawing it is all the caller has to do. The animation
     loops for as long as it keeps being drawn, at the pace the file asks for.
+
+    Pass ``loop=False`` for a one-shot animation, such as a jump: it plays
+    through once, then holds its last frame and reports ``finished``, so the
+    caller can swap in another animation or leave the pose standing. Calling
+    ``restart`` plays it again from the top, which is how the same jump is
+    re-triggered each time the entity leaves the ground.
     """
 
     frames: list[pygame.Surface]
 
-    def __init__(self, anim_path: str) -> None:
+    def __init__(self, anim_path: str, loop: bool = True) -> None:
         """
         Initialize the EntityAnim by loading the animation at ``anim_path``.
 
         Args:
             anim_path (str): The path to the animation file.
+            loop (bool): Whether the animation repeats. Defaults to True.
         """
 
         self.frames = []
+        self.loop: bool = loop
 
         self._starts: list[float] = []
         self._duration: float = 0.0
@@ -43,14 +51,16 @@ def __init__(self, anim_path: str) -> None:
 
         self.set_image(anim_path)
 
-    def set_image(self, anim_path: str) -> None:
+    def set_image(self, anim_path: str, loop: Optional[bool] = None) -> None:
         """
         Load ``anim_path`` and store it as an animation.
 
         The animation starts over from its first frame.
 
         Args:
             anim_path (str): The path to the animation file.
+            loop (Optional[bool]): Whether the animation repeats. Keeps the
+                current setting when None. Defaults to None.
         """
 
         assert pygame.get_init(), (  # nosec B101
@@ -63,6 +73,9 @@ def set_image(self, anim_path: str) -> None:
 
         self.frames = [frame.convert_alpha() for frame, _ in loaded]
 
+        if loop is not None:
+            self.loop = loop
+
         self._starts = []
         self._duration = 0.0
 
@@ -75,6 +88,35 @@ def set_image(self, anim_path: str) -> None:
         self._scaled = None
         self._scaled_key = None
 
+    def restart(self) -> None:
+        """
+        Play the animation again from its first frame.
+
+        This is what re-triggers a one-shot animation: call it on every jump
+        rather than reloading the file each time.
+        """
+
+        self._started_at = pygame.time.get_ticks()
+
+    @property
+    def finished(self) -> bool:
+        """
+        Whether a one-shot animation has already played through its last frame.
+
+        A looping animation never finishes, so this is always False for one.
+
+        Returns:
+            bool: True once a non-looping animation has run its course.
+        """
+
+        if self.loop:
+            return False
+
+        if self._duration <= 0.0:
+            return True
+
+        return (pygame.time.get_ticks() - self._started_at) >= self._duration
+
     def _current_index(self) -> int:
         """
         Work out which frame is due, from how long the animation has been running.
@@ -86,7 +128,13 @@ def _current_index(self) -> int:
         if self._duration <= 0.0:
             return 0
 
-        elapsed: float = (pygame.time.get_ticks() - self._started_at) % self._duration
+        elapsed: float = float(pygame.time.get_ticks() - self._started_at)
+
+        if not self.loop:
+            if elapsed >= self._duration:
+                return len(self.frames) - 1
+        else:
+            elapsed %= self._duration
 
         return bisect.bisect_right(self._starts, elapsed) - 1