mini-arcade-core 0.9.0__py3-none-any.whl → 0.9.2__py3-none-any.whl

mini_arcade_core/__init__.py

@@ -19,6 +19,7 @@ from .collision2d import RectCollider
 from .entity import Entity, KinematicEntity, SpriteEntity
 from .game import Game, GameConfig
 from .geometry2d import Bounds2D, Position2D, Size2D
+from .keys import Key, keymap
 from .kinematics2d import KinematicData
 from .physics2d import Velocity2D
 from .scene import Scene
@@ -69,6 +70,8 @@ __all__ = [
     "VerticalWrap",
     "RectSprite",
     "RectKinematic",
+    "Key",
+    "keymap",
 ]
 
 PACKAGE_NAME = "mini-arcade-core"  # or whatever is in your pyproject.toml

mini_arcade_core/backend.py

@@ -9,6 +9,8 @@ from dataclasses import dataclass
 from enum import Enum, auto
 from typing import Iterable, Optional, Protocol, Tuple, Union
 
+from .keys import Key
+
 Color = Union[Tuple[int, int, int], Tuple[int, int, int, int]]
 
 
@@ -57,7 +59,8 @@ class Event:
     - key: integer key code (e.g. ESC = 27), or None if not applicable
 
     :ivar type (EventType): The type of event.
-    :ivar key (int | None): The key code associated with the event, if any.
+    :ivar key (Key | None): The key associated with the event, if any.
+    :ivar key_code (int | None): The key code associated with the event, if any.
     :ivar scancode (int | None): The hardware scancode of the key, if any.
     :ivar mod (int | None): Modifier keys bitmask, if any.
     :ivar repeat (bool | None): Whether this key event is a repeat, if any.
@@ -72,7 +75,8 @@ class Event:
     """
 
     type: EventType
-    key: Optional[int] = None
+    key: Key | None = None  # Use Key enum for better clarity
+    key_code: Optional[int] = None
 
     # Keyboard extras (optional)
     scancode: Optional[int] = None
@@ -210,6 +214,18 @@ class Backend(Protocol):
         :type color: Color
         """
 
+    def measure_text(self, text: str) -> tuple[int, int]:
+        """
+        Measure the width and height of the given text string in pixels.
+
+        :param text: The text string to measure.
+        :type text: str
+
+        :return: A tuple (width, height) in pixels.
+        :rtype: tuple[int, int]
+        """
+        raise NotImplementedError
+
     def capture_frame(self, path: str | None = None) -> bytes | None:
         """
         Capture the current frame.

mini_arcade_core/keymaps/sdl.py

@@ -0,0 +1,98 @@
+"""
+SDL keymap for mini arcade core.
+Maps SDL keycodes to mini arcade core Key enums.
+"""
+
+from __future__ import annotations
+
+from mini_arcade_core.keys import Key
+
+# SDL keycodes you need (minimal set)
+SDLK_ESCAPE = 27
+SDLK_RETURN = 13
+SDLK_SPACE = 32
+SDLK_TAB = 9
+SDLK_BACKSPACE = 8
+
+SDLK_UP = 1073741906
+SDLK_DOWN = 1073741905
+SDLK_LEFT = 1073741904
+SDLK_RIGHT = 1073741903
+
+F1 = 1073741882
+F2 = 1073741883
+F3 = 1073741884
+F4 = 1073741885
+F5 = 1073741886
+F6 = 1073741887
+F7 = 1073741888
+F8 = 1073741889
+F9 = 1073741890
+F10 = 1073741891
+F11 = 1073741892
+F12 = 1073741893
+
+SDL_KEYCODE_TO_KEY: dict[int, Key] = {
+    # Letters
+    ord("a"): Key.A,
+    ord("b"): Key.B,
+    ord("c"): Key.C,
+    ord("d"): Key.D,
+    ord("e"): Key.E,
+    ord("f"): Key.F,
+    ord("g"): Key.G,
+    ord("h"): Key.H,
+    ord("i"): Key.I,
+    ord("j"): Key.J,
+    ord("k"): Key.K,
+    ord("l"): Key.L,
+    ord("m"): Key.M,
+    ord("n"): Key.N,
+    ord("o"): Key.O,
+    ord("p"): Key.P,
+    ord("q"): Key.Q,
+    ord("r"): Key.R,
+    ord("s"): Key.S,
+    ord("t"): Key.T,
+    ord("u"): Key.U,
+    ord("v"): Key.V,
+    ord("w"): Key.W,
+    ord("x"): Key.X,
+    ord("y"): Key.Y,
+    ord("z"): Key.Z,
+    # Arrows
+    SDLK_UP: Key.UP,
+    SDLK_DOWN: Key.DOWN,
+    SDLK_LEFT: Key.LEFT,
+    SDLK_RIGHT: Key.RIGHT,
+    # Common
+    SDLK_ESCAPE: Key.ESCAPE,
+    SDLK_SPACE: Key.SPACE,
+    SDLK_RETURN: Key.ENTER,
+    SDLK_TAB: Key.TAB,
+    SDLK_BACKSPACE: Key.BACKSPACE,
+    # Numbers
+    ord("0"): Key.NUM_0,
+    ord("1"): Key.NUM_1,
+    ord("2"): Key.NUM_2,
+    ord("3"): Key.NUM_3,
+    ord("4"): Key.NUM_4,
+    ord("5"): Key.NUM_5,
+    ord("6"): Key.NUM_6,
+    ord("7"): Key.NUM_7,
+    ord("8"): Key.NUM_8,
+    ord("9"): Key.NUM_9,
+    # Function keys
+    F1: Key.F1,
+    F2: Key.F2,
+    F3: Key.F3,
+    F4: Key.F4,
+    F5: Key.F5,
+    F6: Key.F6,
+    F7: Key.F7,
+    F8: Key.F8,
+    F9: Key.F9,
+    F10: Key.F10,
+    F11: Key.F11,
+    F12: Key.F12,
+}

mini_arcade_core/keys.py

@@ -0,0 +1,160 @@
+"""
+Mini Arcade Core key definitions.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum, auto
+
+
+class Key(Enum):
+    """
+    Enumeration of common keyboard keys.
+
+    :ivar A-Z: Letter keys.
+    :ivar arrow_up, arrow_down, arrow_left, arrow_right: Arrow keys.
+    :ivar escape, space, enter, tab, backspace: Common control keys.
+    :ivar num_0 - num_9: Number keys.
+    :ivar f1 - f12: Function keys.
+    """
+
+    # Letters
+    A = auto()
+    B = auto()
+    C = auto()
+    D = auto()
+    E = auto()
+    F = auto()
+    G = auto()
+    H = auto()
+    I = auto()
+    J = auto()
+    K = auto()
+    L = auto()
+    M = auto()
+    N = auto()
+    O = auto()
+    P = auto()
+    Q = auto()
+    R = auto()
+    S = auto()
+    T = auto()
+    U = auto()
+    V = auto()
+    W = auto()
+    X = auto()
+    Y = auto()
+    Z = auto()
+
+    # Arrows
+    UP = auto()
+    DOWN = auto()
+    LEFT = auto()
+    RIGHT = auto()
+
+    # Common
+    ESCAPE = auto()
+    SPACE = auto()
+    ENTER = auto()
+    TAB = auto()
+    BACKSPACE = auto()
+
+    # Numbers
+    NUM_0 = auto()
+    NUM_1 = auto()
+    NUM_2 = auto()
+    NUM_3 = auto()
+    NUM_4 = auto()
+    NUM_5 = auto()
+    NUM_6 = auto()
+    NUM_7 = auto()
+    NUM_8 = auto()
+    NUM_9 = auto()
+
+    # Function keys
+    F1 = auto()
+    F2 = auto()
+    F3 = auto()
+    F4 = auto()
+    F5 = auto()
+    F6 = auto()
+    F7 = auto()
+    F8 = auto()
+    F9 = auto()
+    F10 = auto()
+    F11 = auto()
+    F12 = auto()
+
+
+# Justification: Simple alias object for keys
+# pylint: disable=too-many-instance-attributes
+@dataclass(frozen=True)
+class _Keys:
+    # alias object so user code can do keys.w, keys.arrow_up, etc.
+    a: Key = Key.A
+    b: Key = Key.B
+    c: Key = Key.C
+    d: Key = Key.D
+    e: Key = Key.E
+    f: Key = Key.F
+    g: Key = Key.G
+    h: Key = Key.H
+    i: Key = Key.I
+    j: Key = Key.J
+    k: Key = Key.K
+    l: Key = Key.L
+    m: Key = Key.M
+    n: Key = Key.N
+    o: Key = Key.O
+    p: Key = Key.P
+    q: Key = Key.Q
+    r: Key = Key.R
+    s: Key = Key.S
+    t: Key = Key.T
+    u: Key = Key.U
+    v: Key = Key.V
+    w: Key = Key.W
+    x: Key = Key.X
+    y: Key = Key.Y
+    z: Key = Key.Z
+
+    up: Key = Key.UP
+    down: Key = Key.DOWN
+    left: Key = Key.LEFT
+    right: Key = Key.RIGHT
+
+    escape: Key = Key.ESCAPE
+    space: Key = Key.SPACE
+    enter: Key = Key.ENTER
+    tab: Key = Key.TAB
+    backspace: Key = Key.BACKSPACE
+
+    num_0: Key = Key.NUM_0
+    num_1: Key = Key.NUM_1
+    num_2: Key = Key.NUM_2
+    num_3: Key = Key.NUM_3
+    num_4: Key = Key.NUM_4
+    num_5: Key = Key.NUM_5
+    num_6: Key = Key.NUM_6
+    num_7: Key = Key.NUM_7
+    num_8: Key = Key.NUM_8
+    num_9: Key = Key.NUM_9
+
+    f1: Key = Key.F1
+    f2: Key = Key.F2
+    f3: Key = Key.F3
+    f4: Key = Key.F4
+    f5: Key = Key.F5
+    f6: Key = Key.F6
+    f7: Key = Key.F7
+    f8: Key = Key.F8
+    f9: Key = Key.F9
+    f10: Key = Key.F10
+    f11: Key = Key.F11
+    f12: Key = Key.F12
+
+
+# pylint: enable=too-many-instance-attributes
+
+keymap = _Keys()

mini_arcade_core/ui/menu.py

@@ -8,6 +8,7 @@ from dataclasses import dataclass
 from typing import Callable, Sequence
 
 from mini_arcade_core.backend import Backend, Color, Event, EventType
+from mini_arcade_core.geometry2d import Size2D
 
 MenuAction = Callable[[], None]
 
@@ -25,6 +26,9 @@ class MenuItem:
     on_select: MenuAction
 
 
+# Justification: Data container for styling options needs
+# some attributes.
+# pylint: disable=too-many-instance-attributes
 @dataclass
 class MenuStyle:
     """
@@ -37,7 +41,42 @@ class MenuStyle:
 
     normal: Color = (220, 220, 220)
     selected: Color = (255, 255, 0)
+
+    # Layout
     line_height: int = 28
+    title_color: Color = (255, 255, 255)
+    title_spacing: int = 18
+
+    # Scene background (solid)
+    background_color: Color | None = None  # e.g. BACKGROUND
+
+    # Optional full-screen overlay (dim)
+    overlay_color: Color | None = None  # e.g. (0,0,0,0.5) for pause
+
+    # Panel behind content (optional)
+    panel_color: Color | None = None
+    panel_padding_x: int = 24
+    panel_padding_y: int = 18
+
+    # Button rendering (optional)
+    button_enabled: bool = False
+    button_fill: Color = (30, 30, 30, 1.0)
+    button_border: Color = (120, 120, 120, 1.0)
+    button_selected_border: Color = (255, 255, 0, 1.0)
+    button_width: int | None = (
+        None  # if None -> auto-fit to longest label + padding
+    )
+    button_height: int = 40
+    button_gap: int = 20
+    button_padding_x: int = 20  # used for auto-fit + text centering
+
+    # Hint footer (optional)
+    hint: str | None = None
+    hint_color: Color = (200, 200, 200)
+    hint_margin_bottom: int = 50
+
+
+# pylint: enable=too-many-instance-attributes
 
 
 class Menu:
@@ -47,8 +86,8 @@ class Menu:
         self,
         items: Sequence[MenuItem],
         *,
-        x: int = 40,
-        y: int = 40,
+        viewport: Size2D | None = None,
+        title: str | None = None,
         style: MenuStyle | None = None,
     ):
         """
@@ -62,8 +101,8 @@ class Menu:
         :type style: MenuStyle | None
         """
         self.items = list(items)
-        self.x = x
-        self.y = y
+        self.viewport = viewport
+        self.title = title
         self.style = style or MenuStyle()
         self.selected_index = 0
 
@@ -114,6 +153,36 @@ class Menu:
         elif event.key == select_key:
             self.select()
 
+    def _measure_content(self, surface: Backend) -> tuple[int, int, int]:
+        """
+        Returns (content_width, content_height, title_height)
+        where content is items-only (no padding).
+        """
+        if not self.items and not self.title:
+            return 0, 0, 0
+
+        max_w = 0
+        title_h = 0
+
+        if self.title:
+            tw, th = surface.measure_text(self.title)
+            max_w = max(max_w, tw)
+            title_h = th
+
+        # Items
+        for it in self.items:
+            w, _ = surface.measure_text(it.label)
+            max_w = max(max_w, w)
+
+        items_h = len(self.items) * self.style.line_height
+
+        # Total content height includes title block if present
+        content_h = items_h
+        if self.title:
+            content_h += title_h + self.style.title_spacing
+
+        return max_w, content_h, title_h
+
     def draw(self, surface: Backend):
         """
         Draw the menu onto the given backend surface.
@@ -121,15 +190,182 @@ class Menu:
         :param surface: The backend surface to draw on.
         :type surface: Backend
         """
+        if self.viewport is None:
+            raise ValueError(
+                "Menu requires viewport=Size2D for centering/layout"
+            )
+
+        vw, vh = self.viewport.width, self.viewport.height
+
+        # 0) Solid background (for main menus)
+        if self.style.background_color is not None:
+            surface.draw_rect(0, 0, vw, vh, color=self.style.background_color)
+
+        # 1) Overlay (for pause, etc.)
+        if self.style.overlay_color is not None:
+            surface.draw_rect(0, 0, vw, vh, color=self.style.overlay_color)
+
+        # 2) Compute menu content bounds (panel area)
+        content_w, content_h, title_h = self._measure_content(surface)
+
+        pad_x, pad_y = self.style.panel_padding_x, self.style.panel_padding_y
+        panel_w = content_w + pad_x * 2
+        panel_h = content_h + pad_y * 2
+
+        x0 = (vw - panel_w) // 2
+        y0 = (vh - panel_h) // 2
+
+        # Optional vertical offset if you add it later:
+        # y0 += self.style.center_offset_y
+
+        # 3) Panel (optional)
+        if self.style.panel_color is not None:
+            surface.draw_rect(
+                x0, y0, panel_w, panel_h, color=self.style.panel_color
+            )
+
+        # 4) Draw title + items
+        cursor_y = y0 + pad_y
+        x_center = x0 + (panel_w // 2)
+
+        if self.title:
+            self._draw_text_center_x(
+                surface,
+                x_center,
+                cursor_y,
+                self.title,
+                color=self.style.title_color,
+            )
+            cursor_y += title_h + self.style.title_spacing
+
+        if self.style.button_enabled:
+            self._draw_buttons(surface, x_center, cursor_y)
+        else:
+            self._draw_text_items(surface, x_center, cursor_y)
+
+        # 5) Hint footer (optional)
+        if self.style.hint:
+            self._draw_text_center_x(
+                surface,
+                vw // 2,
+                vh - self.style.hint_margin_bottom,
+                self.style.hint,
+                color=self.style.hint_color,
+            )
+
+    def _draw_text_items(
+        self, surface: Backend, x_center: int, cursor_y: int
+    ) -> None:
         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,
+            self._draw_text_center_x(
+                surface,
+                x_center,
+                cursor_y + i * self.style.line_height,
                 item.label,
                 color=color,
             )
+
+    # Justification: Local variables for layout calculations
+    # pylint: disable=too-many-locals
+    def _draw_buttons(
+        self, surface: Backend, x_center: int, cursor_y: int
+    ) -> None:
+        # Determine button width: fixed or auto-fit
+        if self.style.button_width is not None:
+            bw = self.style.button_width
+        else:
+            max_label_w = 0
+            for it in self.items:
+                w, _ = surface.measure_text(it.label)
+                max_label_w = max(max_label_w, w)
+            bw = max_label_w + self.style.button_padding_x * 2
+
+        bh = self.style.button_height
+        gap = self.style.button_gap
+
+        # We treat cursor_y as “top of first button”
+        for i, item in enumerate(self.items):
+            y = cursor_y + i * (bh + gap)
+            x = x_center - bw // 2
+
+            selected = i == self.selected_index
+            border = (
+                self.style.button_selected_border
+                if selected
+                else self.style.button_border
+            )
+
+            # Border rect
+            surface.draw_rect(x - 4, y - 4, bw + 8, bh + 8, color=border)
+            # Fill rect
+            surface.draw_rect(x, y, bw, bh, color=self.style.button_fill)
+
+            # Label color
+            text_color = self.style.selected if selected else self.style.normal
+            tw, th = surface.measure_text(item.label)
+            tx = x + (bw - tw) // 2
+            ty = y + (bh - th) // 2
+            surface.draw_text(tx, ty, item.label, color=text_color)
+
+    # pylint: enable=too-many-locals
+
+    def _measure_content(self, surface: Backend) -> tuple[int, int, int]:
+        # If button mode: content height differs (button_height + gaps)
+        max_w = 0
+        title_h = 0
+
+        if self.title:
+            tw, th = surface.measure_text(self.title)
+            max_w = max(max_w, tw)
+            title_h = th
+
+        if not self.items:
+            content_h = 0
+            if self.title:
+                content_h = title_h
+            return max_w, content_h, title_h
+
+        if self.style.button_enabled:
+            # width: either fixed or auto-fit
+            if self.style.button_width is not None:
+                items_w = self.style.button_width
+            else:
+                max_label_w = 0
+                for it in self.items:
+                    w, _ = surface.measure_text(it.label)
+                    max_label_w = max(max_label_w, w)
+                items_w = max_label_w + self.style.button_padding_x * 2
+
+            max_w = max(max_w, items_w)
+
+            bh = self.style.button_height
+            gap = self.style.button_gap
+            items_h = len(self.items) * bh + (len(self.items) - 1) * gap
+        else:
+            for it in self.items:
+                w, _ = surface.measure_text(it.label)
+                max_w = max(max_w, w)
+            items_h = len(self.items) * self.style.line_height
+
+        content_h = items_h
+        if self.title:
+            content_h += title_h + self.style.title_spacing
+
+        return max_w, content_h, title_h
+
+    @staticmethod
+    def _draw_text_center_x(
+        surface: Backend,
+        x_center: int,
+        y: int,
+        text: str,
+        *,
+        color: Color,
+    ) -> None:
+        w, _ = surface.measure_text(text)
+        surface.draw_text(x_center - (w // 2), y, text, color=color)

{mini_arcade_core-0.9.0.dist-info → mini_arcade_core-0.9.2.dist-info}/METADATA

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

{mini_arcade_core-0.9.0.dist-info → mini_arcade_core-0.9.2.dist-info}/RECORD

@@ -1,16 +1,19 @@
-mini_arcade_core/__init__.py,sha256=2PBNxk-rxjJxPvF6PvpdJ_rat0knyo6a-VRI8sROofI,2554
-mini_arcade_core/backend.py,sha256=Q1yNNLX0Hh-1ItUWDV8k1QHuoGPNKHYeoTHT_CxKGPk,6339
+mini_arcade_core/__init__.py,sha256=7Ioji-MpfSQq4Ok3agVzP4mvcTNiThrY-DTDmVYFKo0,2609
+mini_arcade_core/backend.py,sha256=kB666RiMSpFaxVEi0KIOPGjh4cdCPWDs5vz8MdY37G4,6854
 mini_arcade_core/boundaries2d.py,sha256=H1HkCR1422MkQIEve2DFKvnav4RpvtLx-qTMxzmdDMQ,2610
 mini_arcade_core/collision2d.py,sha256=iq800wsoYQNft3SA-W4jeY1wXhbpz2E7IkIorZBI238,1718
 mini_arcade_core/entity.py,sha256=1AuE-_iMJYHxSyG783fsyByKK8Gx4vWWKMCEPjtgHXw,1776
 mini_arcade_core/game.py,sha256=2DaFRdu7ogrwukh2MRnTh0Hy2r1XcaGSHEpLBNxfqIU,7273
 mini_arcade_core/geometry2d.py,sha256=js791mMpsE_YbEoqtTOsOxNSflvKgSk6VeVKhj9N318,1282
+mini_arcade_core/keymaps/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mini_arcade_core/keymaps/sdl.py,sha256=lRBvgTfdT7enN0qV7S2ZoLsPAWpaiSHzsyVGDlyTzQA,1924
+mini_arcade_core/keys.py,sha256=LTg20SwLBI3kpPIiTNpq2yBft_QUGj-iNFSNm9M-Fus,3010
 mini_arcade_core/kinematics2d.py,sha256=twBx-1jEwdknIJEyYBUg4VZyAvw1d7pGHaGFd36TPbo,2085
 mini_arcade_core/physics2d.py,sha256=qIq86qWVuvcnLIMEPH6xx7XQO4tQhfiMZY6FseuVOR8,1636
 mini_arcade_core/scene.py,sha256=e0E81aHt6saYiGfA-1V2II1yWwcZfvqGTRAv8pZnQtY,3865
 mini_arcade_core/ui/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mini_arcade_core/ui/menu.py,sha256=2CbsMvqebZWbUdhilhyTNDL1LGcdaPqHFsIM_J2MWK8,3636
-mini_arcade_core-0.9.0.dist-info/METADATA,sha256=eLtfBDXL_S0FRergm-Jr4JqgS4S0kDnfmdsVFuVAgEM,8188
-mini_arcade_core-0.9.0.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-mini_arcade_core-0.9.0.dist-info/licenses/LICENSE,sha256=3lHAuV0584cVS5vAqi2uC6GcsVgxUijvwvtZckyvaZ4,1096
-mini_arcade_core-0.9.0.dist-info/RECORD,,
+mini_arcade_core/ui/menu.py,sha256=79krwtWkGXKLSxG37PZsIIeFLayx9OTDN6esJepthlE,11343
+mini_arcade_core-0.9.2.dist-info/METADATA,sha256=6NW5an292zZXvaDVoLUKayukctCRzizdbHqM0a9vZ5g,8188
+mini_arcade_core-0.9.2.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+mini_arcade_core-0.9.2.dist-info/licenses/LICENSE,sha256=3lHAuV0584cVS5vAqi2uC6GcsVgxUijvwvtZckyvaZ4,1096
+mini_arcade_core-0.9.2.dist-info/RECORD,,