mini-arcade-core 0.8.0__tar.gz → 0.8.1__tar.gz

{mini_arcade_core-0.8.0 → mini_arcade_core-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mini-arcade-core
-Version: 0.8.0
+Version: 0.8.1
 Summary: Tiny scene-based game loop core for small arcade games.
 License: Copyright (c) 2025 Santiago Rincón
            

{mini_arcade_core-0.8.0 → mini_arcade_core-0.8.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "mini-arcade-core"
-version = "0.8.0"
+version = "0.8.1"
 description = "Tiny scene-based game loop core for small arcade games."
 authors = [
     { name = "Santiago Rincon", email = "rincores@gmail.com" },

{mini_arcade_core-0.8.0 → mini_arcade_core-0.8.1}/src/mini_arcade_core/game.py

@@ -40,6 +40,12 @@ class GameConfig:
     backend: Backend | None = None
 
 
+@dataclass
+class _StackEntry:
+    scene: "Scene"
+    as_overlay: bool = False
+
+
 class Game:
     """Core game object responsible for managing the main loop and active scene."""
 
@@ -59,6 +65,16 @@ class Game:
                 "GameConfig.backend must be set to a Backend instance"
             )
         self.backend: Backend = config.backend
+        self._scene_stack: list[_StackEntry] = []
+
+    def current_scene(self) -> "Scene | None":
+        """
+        Get the currently active scene.
+
+        :return: The active Scene instance, or None if no scene is active.
+        :rtype: Scene | None
+        """
+        return self._scene_stack[-1].scene if self._scene_stack else None
 
     def change_scene(self, scene: Scene):
         """
@@ -68,10 +84,59 @@ class Game:
         :param scene: The new scene to activate.
         :type scene: Scene
         """
-        if self._current_scene is not None:
-            self._current_scene.on_exit()
-        self._current_scene = scene
-        self._current_scene.on_enter()
+        while self._scene_stack:
+            entry = self._scene_stack.pop()
+            entry.scene.on_exit()
+
+        self._scene_stack.append(_StackEntry(scene=scene, as_overlay=False))
+        scene.on_enter()
+
+    def push_scene(self, scene: "Scene", as_overlay: bool = False):
+        """
+        Push a scene on top of the current one.
+        If as_overlay=True, underlying scene(s) may still be drawn but never updated.
+        """
+        top = self.current_scene()
+        if top is not None:
+            top.on_pause()
+
+        self._scene_stack.append(
+            _StackEntry(scene=scene, as_overlay=as_overlay)
+        )
+        scene.on_enter()
+
+    def pop_scene(self) -> "Scene | None":
+        """Pop the top scene. If stack becomes empty, quit."""
+        if not self._scene_stack:
+            return None
+
+        popped = self._scene_stack.pop()
+        popped.scene.on_exit()
+
+        top = self.current_scene()
+        if top is None:
+            self.quit()
+            return popped.scene
+
+        top.on_resume()
+        return popped.scene
+
+    def _visible_stack(self) -> list["Scene"]:
+        """
+        Return the list of scenes that should be drawn (base + overlays).
+        We draw from the top-most non-overlay scene upward.
+        """
+        if not self._scene_stack:
+            return []
+
+        # find top-most base scene (as_overlay=False)
+        base_idx = 0
+        for i in range(len(self._scene_stack) - 1, -1, -1):
+            if not self._scene_stack[i].as_overlay:
+                base_idx = i
+                break
+
+        return [e.scene for e in self._scene_stack[base_idx:]]
 
     def quit(self):
         """Request that the main loop stops."""
@@ -104,24 +169,27 @@ class Game:
             dt = now - last_time
             last_time = now
 
-            scene = self._current_scene
-            if scene is None:
+            top = self.current_scene()
+            if top is None:
                 break
 
             for ev in backend.poll_events():
-                scene.handle_event(ev)
+                top.handle_event(ev)
 
-            scene.update(dt)
+            top.update(dt)
 
             backend.begin_frame()
-            scene.draw(backend)
+            for scene in self._visible_stack():
+                scene.draw(backend)
             backend.end_frame()
 
             if target_dt > 0 and dt < target_dt:
                 sleep(target_dt - dt)
 
-        if self._current_scene is not None:
-            self._current_scene.on_exit()
+        # exit remaining scenes
+        while self._scene_stack:
+            entry = self._scene_stack.pop()
+            entry.scene.on_exit()
 
     @staticmethod
     def _convert_bmp_to_image(bmp_path: str, out_path: str) -> bool:

{mini_arcade_core-0.8.0 → mini_arcade_core-0.8.1}/src/mini_arcade_core/scene.py

@@ -139,3 +139,9 @@ class Scene(ABC):
         :param surface: The backend surface to draw on.
         :type surface: Backend
         """
+
+    def on_pause(self):
+        """Called when the game is paused."""
+
+    def on_resume(self):
+        """Called when the game is resumed."""

mini_arcade_core-0.8.1/src/mini_arcade_core/ui/menu.py

@@ -0,0 +1,135 @@
+"""
+Menu system for mini arcade core.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Sequence
+
+from mini_arcade_core.backend import Backend, Color, Event, EventType
+
+MenuAction = Callable[[], None]
+
+
+@dataclass(frozen=True)
+class MenuItem:
+    """
+    Represents a single item in a menu.
+
+    :ivar label (str): The text label of the menu item.
+    :ivar on_select (MenuAction): The action to perform when the item is selected.
+    """
+
+    label: str
+    on_select: MenuAction
+
+
+@dataclass
+class MenuStyle:
+    """
+    Styling options for the Menu.
+
+    :ivar normal (Color): Color for unselected items.
+    :ivar selected (Color): Color for the selected item.
+    :ivar line_height (int): Vertical spacing between items.
+    """
+
+    normal: Color = (220, 220, 220)
+    selected: Color = (255, 255, 0)
+    line_height: int = 28
+
+
+class Menu:
+    """A simple text-based menu system."""
+
+    def __init__(
+        self,
+        items: Sequence[MenuItem],
+        *,
+        x: int = 40,
+        y: int = 40,
+        style: MenuStyle | None = None,
+    ):
+        """
+        :param items: Sequence of MenuItem instances to display.
+        type items: Sequence[MenuItem]
+
+        :param x: X coordinate for the menu's top-left corner.
+        :param y: Y coordinate for the menu's top-left corner.
+
+        :param style: Optional MenuStyle for customizing appearance.
+        :type style: MenuStyle | None
+        """
+        self.items = list(items)
+        self.x = x
+        self.y = y
+        self.style = style or MenuStyle()
+        self.selected_index = 0
+
+    def move_up(self):
+        """Move the selection up by one item, wrapping around if necessary."""
+        if self.items:
+            self.selected_index = (self.selected_index - 1) % len(self.items)
+
+    def move_down(self):
+        """Move the selection down by one item, wrapping around if necessary."""
+        if self.items:
+            self.selected_index = (self.selected_index + 1) % len(self.items)
+
+    def select(self):
+        """Select the currently highlighted item, invoking its action."""
+        if self.items:
+            self.items[self.selected_index].on_select()
+
+    def handle_event(
+        self,
+        event: Event,
+        *,
+        up_key: int,
+        down_key: int,
+        select_key: int,
+    ):
+        """
+        Handle an input event to navigate the menu.
+
+        :param event: The input event to handle.
+        :type event: Event
+
+        :param up_key: Key code for moving selection up.
+        type up_key: int
+
+        :param down_key: Key code for moving selection down.
+        :type down_key: int
+
+        :param select_key: Key code for selecting the current item.
+        :type select_key: int
+        """
+        if event.type != EventType.KEYDOWN or event.key is None:
+            return
+        if event.key == up_key:
+            self.move_up()
+        elif event.key == down_key:
+            self.move_down()
+        elif event.key == select_key:
+            self.select()
+
+    def draw(self, surface: Backend):
+        """
+        Draw the menu onto the given backend surface.
+
+        :param surface: The backend surface to draw on.
+        :type surface: Backend
+        """
+        for i, item in enumerate(self.items):
+            color = (
+                self.style.selected
+                if i == self.selected_index
+                else self.style.normal
+            )
+            surface.draw_text(
+                self.x,
+                self.y + i * self.style.line_height,
+                item.label,
+                color=color,
+            )