saga2d 0.2.0__py3-none-any.whl

saga2d/__init__.py

@@ -0,0 +1,43 @@
+"""Saga2D — a small Python framework for 2D games.
+
+Game code imports from here::
+
+    from saga2d import Game, Scene, Sprite, Camera, Label, Button, Anchor
+"""
+
+__version__ = "0.2.0"
+
+import pyglet
+
+# pyglet wraps every GL call in an error check by default; a busy frame makes
+# thousands of them.  The option is read when pyglet.gl loads, so it is set
+# here, before any backend or font module imports it.
+pyglet.options["debug_gl"] = False
+
+from saga2d.actions import Action, Delay, Do, FadeIn, FadeOut, MoveTo, Parallel, PlayAnim, Remove, Repeat, Sequence
+from saga2d.animation import AnimationDef
+from saga2d.assets import AssetManager, AssetNotFoundError
+from saga2d.audio import AudioManager
+from saga2d.backends.base import Event, KeyEvent, MouseEvent, WindowEvent
+from saga2d.game import Game
+from saga2d.hexgrid import HexGrid
+from saga2d.multiplayer_ui import MatchLobby, MatchMenu, add_match_arguments, match_from_arguments
+from saga2d.network import CommandError, MatchClient, MatchHost
+from saga2d.input import InputEvent, InputManager
+from saga2d.rendering import Camera, ParticleEmitter, RenderLayer, Sprite, SpriteAnchor
+from saga2d.save import SaveError, SaveManager
+from saga2d.scene import Scene
+from saga2d.settings import Settings, SettingsError
+from saga2d.ui import Anchor, Button, Column, Component, Image, KeyHints, Label, Layout, Minimap, Panel, ProgressBar, Row, Style, TextStyle, Theme
+from saga2d.util.collision import Rect, aabb_overlap
+from saga2d.util.reactive import ReactiveValue
+from saga2d.util.tween import Ease, tween
+
+__all__ = [
+    "CommandError", "MatchClient", "MatchHost", "MatchLobby", "MatchMenu", "add_match_arguments", "match_from_arguments",
+    "Action", "Anchor", "AnimationDef", "AssetManager", "AssetNotFoundError", "AudioManager", "Button", "Camera",
+    "Column", "Component", "Delay", "Do", "Ease", "Event", "FadeIn", "FadeOut", "Game", "HexGrid", "Image", "InputEvent", "InputManager",
+    "KeyEvent", "KeyHints", "Label", "Layout", "Minimap", "MouseEvent", "MoveTo", "Panel", "Parallel", "ParticleEmitter", "PlayAnim",
+    "ProgressBar", "ReactiveValue", "Rect", "Remove", "RenderLayer", "Repeat", "Row", "SaveError", "SaveManager",
+    "Scene", "Sequence", "Settings", "SettingsError", "Sprite", "SpriteAnchor", "Style", "TextStyle", "Theme", "WindowEvent", "aabb_overlap", "tween",
+]

saga2d/_fileio.py

@@ -0,0 +1,52 @@
+"""Private durable file replacement shared by save slots and preferences.
+
+Callers serialize and validate their data before entering this module. They
+also own backup/recovery policy; this module only stages, syncs and replaces.
+"""
+
+from contextlib import contextmanager
+import os
+from pathlib import Path
+import tempfile
+from collections.abc import Iterator
+
+
+def durable_write(path: Path, data: bytes, *, backup: tuple[Path, bytes] | None = None) -> None:
+    """Replace a file after syncing its bytes, optionally retaining prior data.
+
+    Before the current replacement, a failure leaves the current file intact.
+    A directory-sync failure after replacement is reported even though the
+    replacement may already be visible. A supplied backup remains recoverable.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with _staged_file(path, data) as staged:
+        if backup is not None:
+            backup_path, previous = backup
+            with _staged_file(backup_path, previous) as staged_backup:
+                staged_backup.replace(backup_path)
+                _sync_directory(backup_path.parent)
+        staged.replace(path)
+        _sync_directory(path.parent)
+
+
+@contextmanager
+def _staged_file(path: Path, data: bytes) -> Iterator[Path]:
+    descriptor, name = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.", suffix=".tmp")
+    staged = Path(name)
+    try:
+        with os.fdopen(descriptor, "wb") as stream:
+            stream.write(data)
+            stream.flush()
+            os.fsync(stream.fileno())
+        yield staged
+    finally:
+        staged.unlink(missing_ok=True)
+
+
+def _sync_directory(directory: Path) -> None:
+    if os.name == "posix":
+        descriptor = os.open(directory, os.O_RDONLY)
+        try:
+            os.fsync(descriptor)
+        finally:
+            os.close(descriptor)

saga2d/_scene_stack.py

@@ -0,0 +1,192 @@
+"""SceneStack — scene transitions with deferred application.
+
+Operations requested while the game loop is dispatching input or updating
+are queued and applied afterwards, so a scene never mutates the stack
+underneath its own ``update``.
+"""
+
+from __future__ import annotations
+
+import collections
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from saga2d.game import Game
+    from saga2d.scene import Scene
+
+_logger = logging.getLogger(__name__)
+_MAX_FLUSH_ITERATIONS = 1000
+
+
+class SceneStack:
+    def __init__(self, game: Game) -> None:
+        self._game = game
+        self._stack: list[Scene] = []
+        self._pending: collections.deque[tuple[str, Scene | None]] = collections.deque()
+        self._busy = False  # inside a tick phase, a flush, or a lifecycle hook
+
+    @property
+    def scenes(self) -> list[Scene]:
+        return list(self._stack)
+
+    def top(self) -> Scene | None:
+        return self._stack[-1] if self._stack else None
+
+    @property
+    def transition_pending(self) -> bool:
+        """Whether a callback has requested a scene change for the current phase."""
+        return bool(self._pending)
+
+    def base_index(self) -> int:
+        """Index of the lowest scene that must be drawn."""
+        i = len(self._stack) - 1
+        while i > 0 and self._stack[i].transparent:
+            i -= 1
+        return i
+
+    def get_base_scene(self) -> Scene | None:
+        return self._stack[self.base_index()] if self._stack else None
+
+    # -- Public operations -----------------------------------------------------
+
+    def push(self, scene: Scene) -> None:
+        self._request("push", scene)
+
+    def pop(self) -> None:
+        self._request("pop", None)
+
+    def pop_to(self, scene: Scene) -> None:
+        if self.top() is scene and not self._pending:
+            return
+        self._request("pop_to", scene)
+
+    def replace(self, scene: Scene) -> None:
+        self._request("replace", scene)
+
+    def clear_and_push(self, scene: Scene) -> None:
+        self._request("clear_and_push", scene)
+
+    def _request(self, kind: str, scene: Scene | None) -> None:
+        self._pending.append((kind, scene))
+        if not self._busy:
+            self.flush()
+
+    # -- Tick integration ------------------------------------------------------
+
+    def begin_phase(self) -> None:
+        self._busy = True
+
+    def end_phase(self) -> None:
+        self._busy = False
+        self.flush()
+
+    def flush(self) -> None:
+        if self._busy:
+            return
+        self._busy = True
+        try:
+            iterations = 0
+            while self._pending and iterations < _MAX_FLUSH_ITERATIONS:
+                iterations += 1
+                kind, scene = self._pending.popleft()
+                getattr(self, f"_apply_{kind}")(scene)
+            if self._pending:
+                _logger.warning("SceneStack: %d queued operations discarded after %d iterations", len(self._pending), iterations)
+                self._pending.clear()
+        except BaseException:
+            self._pending.clear()
+            raise
+        finally:
+            self._busy = False
+
+    # -- Application -----------------------------------------------------------
+
+    def _enter(self, scene: Scene) -> None:
+        scene.game = self._game
+        scene._level = len(self._stack)
+        self._stack.append(scene)
+        try:
+            scene.on_enter()
+        except BaseException as enter_error:
+            self._stack.pop()
+            try:
+                scene._release_resources()
+            except BaseException as cleanup_error:
+                raise enter_error from cleanup_error
+            raise
+
+    def _leave(self, scene: Scene) -> None:
+        try:
+            scene.on_exit()
+        finally:
+            scene._release_resources()
+
+    def _apply_push(self, scene: Scene) -> None:
+        if self._stack:
+            self._stack[-1].on_exit()
+        self._enter(scene)
+
+    def _apply_pop(self, _scene: Scene | None) -> None:
+        if not self._stack:
+            return
+        old = self._stack.pop()
+        try:
+            self._leave(old)
+        finally:
+            if self._stack:
+                self._stack[-1].on_reveal()
+
+    def _apply_replace(self, scene: Scene) -> None:
+        if self._stack:
+            self._leave(self._stack.pop())
+        self._enter(scene)
+
+    def _apply_pop_to(self, scene: Scene) -> None:
+        target = next((i for i, item in enumerate(self._stack) if item is scene), None)
+        if target is None:
+            raise ValueError("pop_to target is not on the scene stack")
+        if target == len(self._stack) - 1:
+            return
+        first_error: BaseException | None = None
+        while len(self._stack) > target + 1:
+            try:
+                self._leave(self._stack.pop())
+            except BaseException as exc:
+                first_error = first_error or exc
+        scene.on_reveal()
+        if first_error is not None:
+            raise first_error
+
+    def _apply_clear_and_push(self, scene: Scene) -> None:
+        self.clear()
+        self._enter(scene)
+
+    def clear(self) -> None:
+        """Remove every scene, even if an exit hook fails (used by teardown)."""
+        first_error: BaseException | None = None
+        while self._stack:
+            try:
+                self._leave(self._stack.pop())
+            except BaseException as exc:
+                first_error = first_error or exc
+        if first_error is not None:
+            raise first_error
+
+    # -- Per-frame -------------------------------------------------------------
+
+    def update(self, dt: float) -> None:
+        if not self._stack:
+            return
+        i = len(self._stack) - 1
+        while i > 0 and not self._stack[i].pause_below:
+            i -= 1
+        for scene in self._stack[i:]:
+            scene.update(dt)
+
+    def draw(self) -> None:
+        for scene in self._stack[self.base_index():]:
+            scene.draw()
+            if scene._ui is not None:
+                scene._ui._ensure_layout()
+                scene._ui.draw()