batframework 1.0.8a2__py3-none-any.whl → 1.0.8a3__py3-none-any.whl

batFramework/scene.py

@@ -1,203 +1,305 @@
 from __future__ import annotations
 import re
-from typing import TYPE_CHECKING,Any
+from typing import TYPE_CHECKING, Any
+from collections import OrderedDict
+import itertools
+
 if TYPE_CHECKING:
     from .manager import Manager
+    from .sceneManager import SceneManager
 import pygame
 import batFramework as bf
 
 
 class Scene:
-    def __init__(self, name, enable_alpha=True) -> None:
-        self._name = name
-        self._active = False
-        self._visible = False
-        self._world_entities: list[bf.Entity] = []
-        self._hud_entities: list[bf.Entity] = []
+    def __init__(
+        self,
+        name: str,
+        hud_convert_alpha: bool = True,
+        world_convert_alpha: bool = False,
+    ) -> None:
+        """
+        Initialize the Scene object.
+
+        Args:
+            name: Name of the scene.
+            enable_alpha (bool, optional): Enable alpha channel for the scene surfaces. Defaults to True.
+        """
+        self.scene_index = 0
+        self.name = name
         self.manager: Manager | None = None
+        self.active = False
+        self.visible = False
+        self.world_entities: OrderedDict[bf.Entity, None] = OrderedDict()
+        self.hud_entities: OrderedDict[bf.Entity, None] = OrderedDict()
         self.actions: bf.ActionContainer = bf.ActionContainer()
-        self.camera: bf.Camera = bf.Camera()
-        self.scene_index = 0
-        self.hud_camera: bf.Camera = bf.Camera()
-        if enable_alpha:
-            self.camera.surface = self.camera.surface.convert_alpha()
-            self.hud_camera.surface = self.camera.surface.convert_alpha()
+        self.early_actions: bf.ActionContainer = bf.ActionContainer()
+        self.camera: bf.Camera = bf.Camera(convert_alpha=world_convert_alpha)
+        self.hud_camera: bf.Camera = bf.Camera(convert_alpha=hud_convert_alpha)
 
-            self.camera.set_clear_color((0, 0, 0))
-            self.hud_camera.set_clear_color((0, 0, 0, 0))
-
-        self.root  : bf.Root = bf.Root()
-        self.root.set_center(*self.hud_camera.get_center())
+        self.root: bf.Root = bf.Root(self.hud_camera)
+        self.root.rect.center = self.hud_camera.get_center()
         self.add_hud_entity(self.root)
-        self.blit_calls = 0
 
-    def set_scene_index(self,index):
+    def get_world_entity_count(self) -> int:
+        return len(self.world_entities)
+
+    def get_hud_entity_count(self) -> int:
+        n = 0
+
+        def adder(e):
+            nonlocal n
+            n += len(e.children)
+
+        self.root.visit(adder)
+
+        return len(self.hud_entities) + n
+
+    def set_scene_index(self, index: int):
+        """Set the scene index."""
         self.scene_index = index
 
-    def get_scene_index(self):
+    def get_scene_index(self) -> int:
+        """Get the scene index."""
         return self.scene_index
 
-    def set_sharedVar(self, name, value)->bool:
-        if not self.manager : return False 
+    def set_sharedVar(self, name: str, value: Any) -> bool:
+        """
+        Set a shared variable in the manager.
+
+        Args:
+            name: Name of the shared variable.
+            value: Value to set.
+
+        Returns:
+            bool: True if setting was successful, False otherwise.
+        """
+        if not self.manager:
+            return False
         return self.manager.set_sharedVar(name, value)
 
-    def get_sharedVar(self, name)->Any:
-        if not self.manager : return False 
-        return self.manager.get_sharedVar(name)
+    def get_sharedVar(self, name: str, error_value=None) -> Any:
+        """
+        Get a shared variable from the manager.
+
+        Args:
+            name: Name of the shared variable.
+
+        Returns:
+            Any: Value of the shared variable.
+        """
+        if not self.manager:
+            return error_value
+        return self.manager.get_sharedVar(name, error_value)
 
     def do_when_added(self):
         pass
 
-    def set_clear_color(self, color: pygame.Color|tuple):
+    def set_clear_color(self, color: pygame.Color | tuple):
+        """Set the clear color for the camera."""
         self.camera.set_clear_color(color)
-        # self.hud_camera.set_clear_color(color)
 
     def set_manager(self, manager_link: Manager):
+        """Set the manager link for the scene."""
         self.manager = manager_link
+        self.manager.update_scene_states()
 
     def set_visible(self, value: bool):
-        self._visible = value
-        if self.manager : self.manager.update_scene_states()
+        """Set the visibility of the scene."""
+        self.visible = value
+        if self.manager:
+            self.manager.update_scene_states()
 
     def set_active(self, value):
-        self._active = value
-        if self.manager : self.manager.update_scene_states()
+        """Set the activity of the scene."""
+        self.active = value
+        if self.manager:
+            self.manager.update_scene_states()
 
     def is_active(self) -> bool:
-        return self._active
+        """Check if the scene is active."""
+        return self.active
 
     def is_visible(self) -> bool:
-        return self._visible
+        """Check if the scene is visible."""
+        return self.visible
 
     def get_name(self) -> str:
-        return self._name
-
-    def add_world_entity(self, *entity: bf.Entity):
-        for e in entity:
-            if e not in self._world_entities:
-
-                self._world_entities.append(e)
+        """Get the name of the scene."""
+        return self.name
+
+    def add_world_entity(self, *entities: bf.Entity):
+        """Add world entities to the scene."""
+        for e in entities:
+            if e not in self.world_entities:
+                self.world_entities[e] = None
                 e.parent_scene = self
                 e.do_when_added()
+        self.sort_entities()
 
-    def remove_world_entity(self, *entity: bf.Entity):
-        for e in entity:
-            if e not in self._world_entities:
-                return False
-            e.do_when_removed()
-            e.parent_scene = None
-            self._world_entities.remove(e)
-            return True
-
-    def add_hud_entity(self, *entity: bf.Entity):
-        for e in entity:
-            if e not in self._hud_entities:
-                self._hud_entities.append(e)
+    def remove_world_entity(self, *entities: bf.Entity):
+        """Remove world entities from the scene."""
+        removed = False
+        for e in entities:
+            if e in self.world_entities:
+                e.do_when_removed()
+                e.parent_scene = None
+                del self.world_entities[e]
+                removed = True
+        return removed
+
+    def add_hud_entity(self, *entities: bf.Entity):
+        """Add HUD entities to the scene."""
+        for e in entities:
+            if e not in self.hud_entities:
+                self.hud_entities[e] = None
                 e.parent_scene = self
                 e.do_when_added()
+        self.sort_entities()
+        return True
 
-    def remove_hud_entity(self, *entity: bf.Entity):
-        for e in entity:
-            if e in self._hud_entities:
+    def remove_hud_entity(self, *entities: bf.Entity):
+        """Remove HUD entities from the scene."""
+        for e in entities:
+            if e in self.hud_entities:
                 e.do_when_removed()
                 e.parent_scene = None
-                self._hud_entities.remove(e)
+                del self.hud_entities[e]
 
-    def add_action(self, *action):
-        self.actions.add_action(*action)
+    def add_actions(self, *action):
+        """Add actions to the scene."""
+        self.actions.add_actions(*action)
+
+    def add_early_actions(self, *action):
+        """Add actions to the scene."""
+        self.early_actions.add_actions(*action)
 
     def get_by_tags(self, *tags):
-        return [
+        """Get entities by their tags."""
+        res = [
             entity
-            for entity in self._world_entities + self._hud_entities
-            if any(entity.has_tag(t) for t in tags)
+            for entity in itertools.chain(
+                self.world_entities.keys(), self.hud_entities.keys()
+            )
+            if any(entity.has_tags(t) for t in tags)
         ]
+        res.extend(list(self.root.get_by_tags(*tags)))
+        return res
 
     def get_by_uid(self, uid) -> bf.Entity | None:
-        return next(
-            (
-                entity
-                for entity in self._world_entities + self._hud_entities
-                if entity.uid == uid
-            ),
-            None,
+        """Get an entity by its unique identifier."""
+        res = self._find_entity_by_uid(
+            uid, itertools.chain(self.world_entities.keys(), self.hud_entities.keys())
         )
+        if res is None:
+            res = self._recursive_search_by_uid(uid, self.root)
+        return res
 
-    # called before process event
-    def do_early_process_event(self, event: pygame.Event) -> bool:
-        """return True if stop event propagation in child entities and scene's action container"""
-        return False
+    def _find_entity_by_uid(self, uid, entities) -> bf.Entity | None:
+        """Search for entity by uid in a list of entities."""
+        for entity in entities:
+            if entity.uid == uid:
+                return entity
+        return None
+
+    def _recursive_search_by_uid(self, uid, widget) -> bf.Entity | None:
+        """Recursively search for entity by uid in the widget's children."""
+        if widget.uid == uid:
+            return widget
+
+        for child in widget.children:
+            res = self._recursive_search_by_uid(uid, child)
+            if res is not None:
+                return res
+
+        return None
 
-    # propagates event to all entities
     def process_event(self, event: pygame.Event):
         """
-        Propagates event to child events. Calls early process event first, if returns False then stops. Processes scene's action_container, then custom do_handle_event function.
-        Finally resets the action_container, and propagates to all child entities. if any of them returns True, the propagation is stopped.
+        Propagates event while it is not consumed.
+        In order :
+        -do_early_handle_event()
+        -scene early_actions
+        -propagate to scene entities (hud then world)
+        -do_handle_event()
+        -scene actions
+        at each step, if the event is consumed the propagation stops
         """
-        if self.get_sharedVar("in_transition"):
+        if event.consumed:
             return
-        if self.do_early_process_event(event):
+        self.do_early_handle_event(event)
+        if event.consumed:
             return
-        self.actions.process_event(event)
+        self.early_actions.process_event(event)
+        if event.consumed:
+            return
+        for entity in itertools.chain(
+            self.hud_entities.keys(), self.world_entities.keys()
+        ):
+            entity.process_event(event)
+            if event.consumed:
+                return
         self.do_handle_event(event)
-        for entity in self._world_entities + self._hud_entities:
-            if entity.process_event(event):
-                break
-        self.actions.reset()
+        if event.consumed:
+            return
+        self.actions.process_event(event)
+
+    # called before process event
+    def do_early_handle_event(self, event: pygame.Event):
+        """Called early in event propagation"""
+        pass
 
     def do_handle_event(self, event: pygame.Event):
         """called inside process_event but before resetting the scene's action container and propagating event to child entities of the scene"""
         pass
 
     def update(self, dt):
-        for entity in self._world_entities + self._hud_entities:
+        """Update the scene. Do NOT override"""
+        for entity in itertools.chain(
+            self.hud_entities.keys(), self.world_entities.keys()
+        ):
             entity.update(dt)
         self.do_update(dt)
         self.camera.update(dt)
         self.hud_camera.update(dt)
+        self.actions.reset()
+        self.early_actions.reset()
 
     def do_update(self, dt):
+        """Specific update within the scene."""
         pass
 
     def debug_entity(self, entity: bf.Entity, camera: bf.Camera):
-        # return
-        if not entity.visible:
-            return
-        for data in entity.get_bounding_box():
-            if isinstance(data,pygame.FRect):
+        def draw_rect(data):
+            if data is None:
+                return
+            if isinstance(data, pygame.FRect) or isinstance(data, pygame.Rect):
                 rect = data
-                color = entity._debug_color
+                color = entity.debug_color
             else:
                 rect = data[0]
                 color = data[1]
-            if not isinstance(color,pygame.Color): color = pygame.Color(color)
+            pygame.draw.rect(camera.surface, color, camera.world_to_screen(rect), 1)
 
-            pygame.draw.rect(camera.surface, color , camera.transpose(rect), 1)
+        [draw_rect(data) for data in entity.get_debug_outlines()]
 
-    def draw(self, surface: pygame.Surface):
-        self._world_entities.sort(key=lambda e: (e.z_depth,e.render_order))
-        self._hud_entities.sort(key=lambda e: (e.z_depth,e.render_order))
+    def sort_entities(self) -> None:
+        """Sort entities within the scene based on their rendering order."""
+        self.world_entities = OrderedDict(
+            sorted(self.world_entities.items(), key=lambda e: e[0].render_order)
+        )
+        self.hud_entities = OrderedDict(
+            sorted(self.hud_entities.items(), key=lambda e: e[0].render_order)
+        )
 
-        total_blit_calls = 0
+    def draw(self, surface: pygame.Surface):
         self.camera.clear()
         self.hud_camera.clear()
 
-
-        total_blit_calls += sum(
-            entity.draw(self.camera) for entity in self._world_entities
-        )
-
-        if self.manager and  self.manager._debugging == 2:
-            for entity in self._world_entities:
-                self.debug_entity(entity, self.camera)
-
-        total_blit_calls += sum(
-            entity.draw(self.hud_camera) for entity in self._hud_entities
-        )
-        if  self.manager and  self.manager._debugging == 2:
-            for entity in self._hud_entities:
-                self.debug_entity(entity, self.hud_camera)
-
+        # Draw all world entities
+        self._draw_camera(self.camera, self.world_entities.keys())
+        # Draw all HUD entities
+        self._draw_camera(self.hud_camera, self.hud_entities.keys())
 
         self.do_early_draw(surface)
         self.camera.draw(surface)
@@ -205,7 +307,12 @@ class Scene:
         self.hud_camera.draw(surface)
         self.do_final_draw(surface)
 
-        self.blit_calls = total_blit_calls
+    def _draw_camera(self, camera: bf.Camera, entity_list):
+        _ = [entity.draw(camera) for entity in entity_list]
+        debugMode = self.manager.debug_mode
+        # Draw outlines for world entities if required
+        if debugMode == bf.debugMode.OUTLINES:
+            [self.debug_entity(e, camera) for e in entity_list]
 
     def do_early_draw(self, surface: pygame.Surface):
         pass
@@ -219,8 +326,29 @@ class Scene:
     def on_enter(self):
         self.set_active(True)
         self.set_visible(True)
+        self.root.clear_hovered()
+        # self.root.clear_focused()
+        self.root.build()
+        self.do_on_enter()
+        # self.root.visit(lambda e : e.resolve_constraints())
 
     def on_exit(self):
+        self.root.clear_hovered()
+        # self.root.clear_focused()
         self.set_active(False)
         self.set_visible(False)
         self.actions.hard_reset()
+        self.early_actions.hard_reset()
+        self.do_on_exit()
+
+    def do_on_enter(self) -> None:
+        pass
+
+    def do_on_exit(self) -> None:
+        pass
+
+    def do_on_enter_early(self) -> None:
+        pass
+
+    def do_on_exit_early(self) -> None:
+        pass