arcade-machine-sdk 1.0.0__tar.gz

arcade_machine_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: arcade-machine-sdk
+Version: 1.0.0
+Summary: SDK oficial para crear juegos compatibles con el Arcade Machine Core.
+Author: Neritoou
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Neritoou/arcade-machine-sdk
+Project-URL: Repository, https://github.com/Neritoou/arcade-machine-sdk
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pygame>=2.6.0

arcade_machine_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "arcade-machine-sdk"
+version = "1.0.0"
+description = "SDK oficial para crear juegos compatibles con el Arcade Machine Core."
+authors = [
+    { name = "Neritoou" }
+]
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "pygame>=2.6.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/Neritoou/arcade-machine-sdk"
+Repository = "https://github.com/Neritoou/arcade-machine-sdk"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+arcade_machine_sdk = ["py.typed"]

arcade_machine_sdk-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

arcade_machine_sdk-1.0.0/src/arcade_machine_sdk/__init__.py

@@ -0,0 +1,13 @@
+from .constants import BASE_RESOLUTION, BASE_WIDTH, BASE_HEIGHT, DEFAULT_FPS
+from .game import GameBase, GameMeta
+from .util import json
+
+__all__ = [
+    "BASE_RESOLUTION",
+    "DEFAULT_FPS",
+    "BASE_WIDTH",
+    "BASE_HEIGHT",
+    "GameBase",
+    "GameMeta",
+    "json"
+]

arcade_machine_sdk-1.0.0/src/arcade_machine_sdk/constants/__init__.py

@@ -0,0 +1,8 @@
+from .values import BASE_RESOLUTION, BASE_HEIGHT, BASE_WIDTH, DEFAULT_FPS
+
+__all__ = [
+    "BASE_RESOLUTION", 
+    "BASE_HEIGHT",
+    "BASE_WIDTH",
+    "DEFAULT_FPS"
+]

arcade_machine_sdk-1.0.0/src/arcade_machine_sdk/constants/values.py

@@ -0,0 +1,7 @@
+# Resolución por defecto
+BASE_WIDTH = 1024
+BASE_HEIGHT = 768
+BASE_RESOLUTION = (BASE_WIDTH, BASE_HEIGHT)
+
+# FPS por defecto
+DEFAULT_FPS = 60

arcade_machine_sdk-1.0.0/src/arcade_machine_sdk/game/__init__.py

@@ -0,0 +1,7 @@
+from .game_base import GameBase
+from .game_meta import GameMeta
+
+__all__ = [
+    "GameBase", 
+    "GameMeta"
+]

arcade_machine_sdk-1.0.0/src/arcade_machine_sdk/game/game_base.py

@@ -0,0 +1,134 @@
+from abc import ABC, abstractmethod
+from .game_meta import GameMeta
+from ..constants import BASE_RESOLUTION, DEFAULT_FPS
+import pygame
+
+class GameBase(ABC):
+    """
+    Clase base que todo juego debe implementar para integrarse al Core.
+
+    Arquitectura pensada para un loop único del Core:
+      - El Core mantiene la ventana y el loop global.
+      - Los juegos nunca crean su propio loop ni su propia ventana.
+      - Cada juego expone métodos que el Core llama por frame.
+
+    Flags importantes:
+      - running: True cuando el juego está activo.
+    """
+    def __init__(self, metadata: GameMeta) -> None:
+        metadata.validate()
+        self._running = False
+        self.metadata = metadata
+        self.__surface = None
+
+    def start(self, surface: pygame.Surface) -> None:
+        """
+        Marca el juego como activo.
+        - Su uso en clases concretas debe llamar a **super()**.
+        - Se llama cada vez que el usuario inicia el juego desde el menú del Core.
+        - A este método se le debe pasar una superficie en la que el juego se dibujará.
+
+        args:
+            **screen**: Pantalla o superficie en la que el juego se dibujará.
+        """
+        self._running = True
+        self.__surface = surface
+
+    def stop(self) -> None:
+        """
+        Detiene el juego, libera recursos dinámicos si es necesario.
+        - Su uso en clases concretas debe llamar a **super()**.
+        - Se llama cuando el usuario vuelve al menú o cierra el juego.
+        """
+        self._running = False
+
+    @abstractmethod
+    def handle_events(self, events: list[pygame.event.Event]) -> None:
+        """
+        Recibe los eventos que pasan por el Core (teclado, mouse, joystick)
+        y los procesa para la lógica del juego.
+        - Nunca debe llamar a `pygame.event.get()` por sí mismo.
+
+        args:
+            **events**: lista de eventos de pygame capturados en el frame actual
+        """
+        pass
+
+    @abstractmethod
+    def update(self, dt: float) -> None:
+        """
+        Actualización de la lógica del juego por frame.
+        - Se llama solo si `_running=True`.
+
+        args:
+            **dt**: tiempo en segundos desde el último frame (para movimientos independientes del FPS)
+        """
+        pass
+    
+    @abstractmethod
+    def render(self) -> None:
+        """
+        Dibuja todo el estado del juego en la superficie que pasa el Core.
+        - Nunca crea su propia ventana.
+        - Se llama solo si `_running=True`.
+        """
+        pass
+
+    @property
+    def running(self) -> bool:
+        """
+        Devuelve el estado actual del juego (activo o no).
+        Útil para el Core para saber si debe llamar a update() y render().
+        """
+        return self._running
+    
+    @property
+    def surface(self) -> pygame.Surface:
+        """
+        Devuelve la superficie actual en la que el juego se está dibujando.
+        """
+        if self.__surface == None:
+            raise AttributeError("No hay ninguna superficie disponible")
+        return self.__surface
+
+    def run_independently(self) -> None:
+        """
+        Ejecuta el juego de forma independiente sin necesidad del Core.
+        Útil para desarrollo y testing.
+        """
+        if not pygame.get_init():
+            pygame.init()
+
+        screen = pygame.display.set_mode(BASE_RESOLUTION)
+        pygame.display.set_caption(self.metadata.title)
+        clock = pygame.time.Clock()
+        self.start(screen)
+
+        try:
+            while self._running:
+                events = pygame.event.get()
+
+                for event in events:
+                    if event.type == pygame.QUIT:
+                        self.stop()
+                        break
+
+                if self._running:
+                    self.handle_events(events)
+
+                if self._running:
+                    dt = clock.get_time() / 1000.0
+                    self.update(dt)
+
+                if self._running:
+                    self.render()
+                    pygame.display.flip()
+
+                clock.tick(DEFAULT_FPS)
+
+        except KeyboardInterrupt:
+            pass
+        
+        finally:
+            self.stop()
+            pygame.quit()

arcade_machine_sdk-1.0.0/src/arcade_machine_sdk/game/game_meta.py

@@ -0,0 +1,81 @@
+class GameMeta:
+    """Clase que sigue el patrón Builder para construir metadatos de un juego."""
+    
+    def __init__(self) -> None:
+        self._title = ""
+        self._description = ""
+        self._release_date = ""
+        self._tags: list[str] = []
+        self._group_number = -1
+        self._authors: list[str] = []
+    
+    def with_title(self, title: str) -> 'GameMeta':
+        self._title = title
+        return self
+    
+    def with_description(self, description: str) -> 'GameMeta':
+        self._description = description
+        return self
+    
+    # TODO: esto debería representarse con un UNIX timestamp o una fecha de Python, pero por ahora se puede dejar así. Además, es siquiera esto necesario?
+    def with_release_date(self, release_date: str) -> 'GameMeta':
+        self._release_date = release_date
+        return self
+    
+    def with_tags(self, tags: list[str]) -> 'GameMeta':
+        self._tags.extend(tags)
+        return self
+    
+    def add_tag(self, tag: str) -> 'GameMeta':
+        self._tags.append(tag)
+        return self
+    
+    def with_group_number(self, group_number: int) -> 'GameMeta':
+        self._group_number = group_number
+        return self
+    
+    def with_authors(self, authors: list[str]) -> 'GameMeta':
+        self._authors.extend(authors)
+        return self
+    
+    def add_author(self, author: str) -> 'GameMeta':
+        self._authors.append(author)
+        return self
+    
+    @property
+    def title(self) -> str:
+        return self._title
+    
+    @property
+    def description(self) -> str:
+        return self._description
+    
+    @property
+    def release_date(self) -> str:
+        return self._release_date
+    
+    @property
+    def tags(self) -> list[str]:
+        return self._tags.copy()
+    
+    @property
+    def group_number(self) -> int:
+        return self._group_number
+    
+    @property
+    def authors(self) -> list[str]:
+        return self._authors.copy()
+    
+    def validate(self) -> None:
+        if not self._title:
+            raise ValueError(f"No se especificó un título (\"title\") para el juego en sus metadatos")
+        if not self._description:
+            raise ValueError(f"No se especificó una descripción (\"description\") para el juego en sus metadatos")
+        if not self._release_date:
+            raise ValueError(f"No se especificó una fecha de lanzamiento (\"release_date\") para el juego en sus metadatos")
+        if not self._tags:
+            raise ValueError(f"No se especificó al menos una etiqueta (\"tags\") para el juego en sus metadatos")
+        if self._group_number == -1:
+            raise ValueError(f"No se especificó el número del grupo (\"group_number\") que hizo el juego en sus metadatos")
+        if not self._authors:
+            raise ValueError(f"No se especificó al menos un autor (\"authors\") que haya hecho el juego en sus metadatos")

arcade_machine_sdk-1.0.0/src/arcade_machine_sdk/util/__init__.py

@@ -0,0 +1,6 @@
+from .json import load, save
+
+__all__ = [
+    "load", 
+    "save"
+]

arcade_machine_sdk-1.0.0/src/arcade_machine_sdk/util/json.py

@@ -0,0 +1,32 @@
+import json
+from pathlib import Path
+from typing import Any
+
+def load(file_path: str) -> dict[str, Any]:
+    """
+    Carga un archivo JSON y devuelve un diccionario.
+
+    args:
+        **file_path**: Ruta completa al archivo JSON.
+
+    returns:
+        Diccionario con los datos del JSON.
+    """
+    path = Path(file_path)
+    if not path.exists():
+        raise FileNotFoundError(f"No se encontró el archivo JSON en {file_path}")
+
+    with path.open("r", encoding="utf-8") as f:
+        return json.load(f)
+
+def save(file_path: str, data: dict[str, Any]) -> None:
+    """
+    Guarda un diccionario como un archivo JSON.
+
+    args:
+        **file_path**: Ruta completa al archivo JSON.
+        **json**: Diccionario a escribir como JSON.
+    """
+    path = Path(file_path)
+    with path.open("w", encoding="utf-8") as f:
+        json.dump(data, f, ensure_ascii=False, indent=4)

arcade_machine_sdk-1.0.0/src/arcade_machine_sdk.egg-info/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: arcade-machine-sdk
+Version: 1.0.0
+Summary: SDK oficial para crear juegos compatibles con el Arcade Machine Core.
+Author: Neritoou
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Neritoou/arcade-machine-sdk
+Project-URL: Repository, https://github.com/Neritoou/arcade-machine-sdk
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pygame>=2.6.0

arcade_machine_sdk-1.0.0/src/arcade_machine_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+src/arcade_machine_sdk/__init__.py
+src/arcade_machine_sdk/py.typed
+src/arcade_machine_sdk.egg-info/PKG-INFO
+src/arcade_machine_sdk.egg-info/SOURCES.txt
+src/arcade_machine_sdk.egg-info/dependency_links.txt
+src/arcade_machine_sdk.egg-info/requires.txt
+src/arcade_machine_sdk.egg-info/top_level.txt
+src/arcade_machine_sdk/constants/__init__.py
+src/arcade_machine_sdk/constants/values.py
+src/arcade_machine_sdk/game/__init__.py
+src/arcade_machine_sdk/game/game_base.py
+src/arcade_machine_sdk/game/game_meta.py
+src/arcade_machine_sdk/util/__init__.py
+src/arcade_machine_sdk/util/json.py

arcade_machine_sdk-1.0.0/src/arcade_machine_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

arcade_machine_sdk-1.0.0/src/arcade_machine_sdk.egg-info/requires.txt

@@ -0,0 +1 @@
+pygame>=2.6.0

arcade_machine_sdk-1.0.0/src/arcade_machine_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+arcade_machine_sdk