pygkit 1.0.1__py3-none-any.whl

pygkit/__init__.py

@@ -0,0 +1,41 @@
+from .audio import *
+from .transitions import *
+from .ui import *
+from .utils import *
+
+__all__ = [
+    "SoundManager",
+    "SFX_CHANNELS",
+    "TransitionRunner",
+    "TransitionState",
+    "FadeToBlack",
+    "FadeFromBlack",
+    "Crossfade",
+    "Flash",
+    "IrisIn",
+    "IrisOut",
+    "Slide",
+    "PixelDissolve",
+    "Shake",
+    "Container",
+    "CooldownOverlay",
+    "ProgressBarUI",
+    "UIBase",
+    "UIOptions",
+    "BoxModel",
+    "BoxModelResult",
+    "generate_box_model",
+    "SimpleInterpolation",
+    "Timer",
+    "lerp",
+    "smoothstep",
+    "ease_in_out",
+    "ease_out",
+    "ease_in",
+    "load_font",
+    "outline",
+    "shadow",
+    "wrap",
+    "render_multiline",
+    "fit",
+]

pygkit/audio/__init__.py

@@ -0,0 +1,6 @@
+from .soundmanager import SFX_CHANNELS, SoundManager
+
+__all__ = [
+    "SoundManager",
+    "SFX_CHANNELS",
+]

pygkit/audio/soundmanager.py

@@ -0,0 +1,89 @@
+from pathlib import Path
+from typing import Dict, Literal
+
+import pygame
+from pygame import Channel, Sound
+
+SFX_CHANNELS = 6
+
+
+class SoundManager:
+    def __init__(self, num_channels: int = 8, main_channels: int = 2) -> None:
+        if pygame.mixer.get_init() is None:
+            raise RuntimeError("pygame.mixer not initialized")
+
+        if main_channels + SFX_CHANNELS > num_channels:
+            num_channels = main_channels + SFX_CHANNELS
+
+        self._main: Dict[str, Sound] = {}
+        self._sfx: Dict[str, Sound] = {}
+
+        self._num_channels = num_channels
+        self._main_count = main_channels
+        self._channels = tuple(pygame.Channel(i) for i in range(num_channels))
+        self._next_sfx = main_channels
+
+    def add_sound(
+        self, path: Path, key: str, kind: Literal["main", "sfx"] = "sfx"
+    ) -> bool:
+        scope = self._main if kind == "main" else self._sfx
+        try:
+            scope[key] = pygame.Sound(str(path))
+            return True
+        except (FileNotFoundError, TypeError, pygame.error) as e:
+            return False
+
+    def play(
+        self,
+        key: str,
+        kind: Literal["main", "sfx"] = "sfx",
+        channel_id: int | None = None,
+        loops: int | None = None,
+    ) -> None:
+        scope = self._main if kind == "main" else self._sfx
+        sound = scope.get(key)
+        if sound is None:
+            raise KeyError(f"Unknown sound '{key}'")
+
+        if loops is None:
+            loops = -1 if kind == "main" else 0
+
+        if channel_id is not None:
+            self._channels[channel_id].stop()
+            self._channels[channel_id].play(sound, loops)
+            return
+
+        channel = self._assign(kind)
+        channel.play(sound, loops)
+
+    def stop_all(self) -> None:
+        for ch in self._channels:
+            ch.stop()
+
+    def stop_channel(self, channel_id: int) -> None:
+        self._channels[channel_id].stop()
+
+    def get_channel(self, channel_id: int) -> Channel:
+        return self._channels[channel_id]
+
+    def _assign(self, kind: Literal["main", "sfx"]) -> Channel:
+        if kind == "main":
+            for idx in range(self._main_count):
+                ch = self._channels[idx]
+                if not ch.get_busy():
+                    return ch
+            ch = self._channels[0]
+            ch.stop()
+            return ch
+
+        for idx in range(self._main_count, self._num_channels):
+            ch = self._channels[idx]
+            if not ch.get_busy():
+                return ch
+
+        ch = self._channels[self._next_sfx]
+        ch.stop()
+        self._next_sfx += 1
+        if self._next_sfx >= self._num_channels:
+            self._next_sfx = self._main_count
+        return ch

pygkit/protocols.py

@@ -0,0 +1,29 @@
+from typing import Protocol
+
+from pygame import Surface
+
+
+class Renderable(Protocol):
+    def render(self, screen: Surface, pos_offset: tuple[int, int] = (0, 0)): ...
+
+    def update(self): ...
+
+
+class UIElement(Protocol):
+    def render(self, screen: Surface): ...
+
+    def update(self): ...
+
+    @property
+    def size(self) -> tuple[int, int]: ...
+
+    @property
+    def pos(self) -> tuple[int, int]: ...
+
+
+class Drawable(Protocol):
+    def draw(self, surface: Surface): ...
+
+
+class Updateable(Protocol):
+    def update(self): ...

pygkit/transitions/__init__.py

@@ -0,0 +1,18 @@
+from .base import TransitionRunner, TransitionState
+from .effects import PixelDissolve, Shake
+from .fades import Crossfade, FadeFromBlack, FadeToBlack, Flash
+from .wipes import IrisIn, IrisOut, Slide
+
+__all__ = [
+    "TransitionRunner",
+    "TransitionState",
+    "FadeToBlack",
+    "FadeFromBlack",
+    "Crossfade",
+    "Flash",
+    "IrisIn",
+    "IrisOut",
+    "Slide",
+    "PixelDissolve",
+    "Shake",
+]

pygkit/transitions/base.py

@@ -0,0 +1,97 @@
+from enum import Enum, auto
+from typing import Protocol
+
+from pygame import Surface
+
+
+class Transition(Protocol):
+    def start(self, duration: float) -> None: ...
+
+    def update(self, dt: float) -> None: ...
+
+    def render(
+        self,
+        screen: Surface,
+        source: Surface | None = None,
+        target: Surface | None = None,
+    ) -> None: ...
+
+    @property
+    def done(self) -> bool: ...
+
+    def reset(self) -> None: ...
+
+
+class TransitionState(Enum):
+    IDLE = auto()
+    OUT = auto()
+    IN = auto()
+    DONE = auto()
+
+
+class TransitionRunner:
+    __slots__ = ("fade_out", "fade_in", "state")
+
+    def __init__(
+        self, fade_out: Transition | None = None, fade_in: Transition | None = None
+    ) -> None:
+        self.fade_out = fade_out
+        self.fade_in = fade_in
+        self.state = TransitionState.IDLE
+
+    def start_out(self, duration: float = 0.5) -> None:
+        if self.fade_out is not None:
+            self.fade_out.start(duration)
+        self.state = TransitionState.OUT
+
+    def start_in(self, duration: float = 0.5) -> None:
+        if self.fade_in is not None:
+            self.fade_in.start(duration)
+        self.state = TransitionState.IN
+
+    def update(self, dt: float) -> None:
+        if self.state is TransitionState.OUT:
+            if self.fade_out is not None:
+                self.fade_out.update(dt)
+                if self.fade_out.done:
+                    self.state = TransitionState.IDLE
+            else:
+                self.state = TransitionState.IDLE
+        elif self.state is TransitionState.IN:
+            if self.fade_in is not None:
+                self.fade_in.update(dt)
+                if self.fade_in.done:
+                    self.state = TransitionState.DONE
+            else:
+                self.state = TransitionState.DONE
+
+    def render(
+        self,
+        screen: Surface,
+        source: Surface | None = None,
+        target: Surface | None = None,
+    ) -> None:
+        if self.state is TransitionState.OUT and self.fade_out is not None:
+            self.fade_out.render(screen, source=source, target=None)
+        elif self.state is TransitionState.IN and self.fade_in is not None:
+            self.fade_in.render(screen, source=None, target=target)
+        elif self.state is TransitionState.DONE and target is not None:
+            screen.blit(target, (0, 0))
+
+    @property
+    def done_out(self) -> bool:
+        return (
+            self.state is TransitionState.IDLE
+            and (self.fade_out is None or self.fade_out.done)
+        )
+
+    @property
+    def done(self) -> bool:
+        return self.state is TransitionState.DONE
+
+    def reset(self) -> None:
+        if self.fade_out is not None:
+            self.fade_out.reset()
+        if self.fade_in is not None:
+            self.fade_in.reset()
+        self.state = TransitionState.IDLE

pygkit/transitions/effects.py

@@ -0,0 +1,156 @@
+import math
+import random
+
+from pygame import Surface
+
+from ..utils.interpolation import ease_out
+
+
+class PixelDissolve:
+    """
+    Transitions from source to target by revealing randomly-ordered tiles.
+    """
+
+    __slots__ = (
+        "_tile_size",
+        "_easing",
+        "_elapsed",
+        "_duration",
+        "_done",
+        "_order",
+        "_cols",
+        "_rows",
+    )
+
+    def __init__(self, tile_size: int = 8) -> None:
+        self._tile_size = tile_size
+        self._easing = ease_out
+        self._elapsed = 0.0
+        self._duration = 0.0
+        self._done = False
+        self._order: list[int] = []
+        self._cols = 0
+        self._rows = 0
+
+    def start(self, duration: float) -> None:
+        self._elapsed = 0.0
+        self._duration = duration
+        self._done = False
+        self._order = []
+
+    @property
+    def done(self) -> bool:
+        return self._done
+
+    def reset(self) -> None:
+        self._elapsed = 0.0
+        self._duration = 0.0
+        self._done = False
+        self._order.clear()
+        self._cols = 0
+        self._rows = 0
+
+    def update(self, dt: float) -> None:
+        if self._done:
+            return
+        self._elapsed += dt
+        if self._elapsed >= self._duration:
+            self._elapsed = self._duration
+            self._done = True
+
+    def render(
+        self,
+        screen: Surface,
+        source: Surface | None = None,
+        target: Surface | None = None,
+    ) -> None:
+        w, h = screen.get_size()
+        ts = self._tile_size
+        cols = max(1, int(math.ceil(w / ts)))
+        rows = max(1, int(math.ceil(h / ts)))
+
+        if not self._order:
+            self._cols = cols
+            self._rows = rows
+            self._order = list(range(cols * rows))
+            random.shuffle(self._order)
+
+        t = self._elapsed / self._duration if self._duration > 0 else 1.0
+        reveal_count = int(t * len(self._order))
+
+        revealed = set(self._order[:reveal_count])
+
+        for idx in range(cols * rows):
+            gx = idx % cols
+            gy = idx // cols
+            rx = gx * ts
+            ry = gy * ts
+
+            if idx in revealed and target is not None:
+                screen.blit(target, (rx, ry), (rx, ry, ts, ts))
+            elif source is not None:
+                screen.blit(source, (rx, ry), (rx, ry, ts, ts))
+
+        if self._done and target is not None:
+            screen.blit(target, (0, 0))
+
+
+class Shake:
+    """
+    Camera shake effect.
+    Offsets the screen blit by a decaying random offset.
+    Can be used standalone or alongside another transition.
+    """
+
+    __slots__ = ("_intensity", "_elapsed", "_duration", "_done", "_offset")
+
+    def __init__(self, intensity: float = 8.0) -> None:
+        self._intensity = intensity
+        self._elapsed = 0.0
+        self._duration = 0.0
+        self._done = False
+        self._offset = (0, 0)
+
+    def start(self, duration: float = 0.3) -> None:
+        self._elapsed = 0.0
+        self._duration = duration
+        self._done = False
+
+    @property
+    def done(self) -> bool:
+        return self._done
+
+    def reset(self) -> None:
+        self._elapsed = 0.0
+        self._duration = 0.0
+        self._done = False
+        self._offset = (0, 0)
+
+    def update(self, dt: float) -> None:
+        if self._done:
+            return
+        self._elapsed += dt
+        if self._elapsed >= self._duration:
+            self._elapsed = self._duration
+            self._done = True
+            self._offset = (0, 0)
+            return
+
+        t = self._elapsed / self._duration
+        decay = 1.0 - t
+        current = self._intensity * decay
+
+        ox = random.uniform(-current, current)
+        oy = random.uniform(-current, current)
+        self._offset = (int(ox), int(oy))
+
+    def render(
+        self,
+        screen: Surface,
+        source: Surface | None = None,
+        target: Surface | None = None,
+    ) -> None:
+        surf = target if target is not None else source
+        if surf is not None:
+            ox, oy = self._offset
+            screen.blit(surf, (ox, oy))

pygkit/transitions/fades.py

@@ -0,0 +1,196 @@
+from typing import Callable
+
+from pygame import SRCALPHA, Surface
+
+from ..utils.interpolation import ease_in_out
+
+
+class _FadeBase:
+    __slots__ = ("_color", "_easing", "_overlay", "_elapsed", "_duration", "_done")
+
+    def __init__(
+        self,
+        color: tuple[int, int, int] = (0, 0, 0),
+        easing: Callable[[float], float] = ease_in_out,
+    ) -> None:
+        self._color = color
+        self._easing = easing
+        self._overlay: Surface | None = None
+        self._elapsed = 0.0
+        self._duration = 0.0
+        self._done = True
+
+    def start(self, duration: float) -> None:
+        self._elapsed = 0.0
+        self._duration = duration
+        self._done = False
+
+    @property
+    def done(self) -> bool:
+        return self._done
+
+    def reset(self) -> None:
+        self._elapsed = 0.0
+        self._duration = 0.0
+        self._done = False
+        self._overlay = None
+
+
+class FadeToBlack(_FadeBase):
+    """
+    Fades the source surface to black.
+    """
+
+    def update(self, dt: float) -> None:
+        if self._done:
+            return
+        self._elapsed += dt
+        if self._elapsed >= self._duration:
+            self._elapsed = self._duration
+            self._done = True
+
+    def render(
+        self,
+        screen: Surface,
+        source: Surface | None = None,
+        target: Surface | None = None,
+    ) -> None:
+        if source is not None:
+            screen.blit(source, (0, 0))
+
+        t = self._easing(self._elapsed / self._duration) if self._duration > 0 else 1.0
+        alpha = int(t * 255)
+
+        if alpha > 0:
+            size = screen.get_size()
+            if (
+                self._overlay is None
+                or self._overlay.get_size() != size
+            ):
+                self._overlay = Surface(size, SRCALPHA)
+            self._overlay.fill((*self._color, alpha))
+            screen.blit(self._overlay, (0, 0))
+
+
+class FadeFromBlack(_FadeBase):
+    """
+    Fades from black to reveal the target surface.
+    """
+
+    def update(self, dt: float) -> None:
+        if self._done:
+            return
+        self._elapsed += dt
+        if self._elapsed >= self._duration:
+            self._elapsed = self._duration
+            self._done = True
+
+    def render(
+        self,
+        screen: Surface,
+        source: Surface | None = None,
+        target: Surface | None = None,
+    ) -> None:
+        if target is not None:
+            screen.blit(target, (0, 0))
+
+        t = self._easing(self._elapsed / self._duration) if self._duration > 0 else 1.0
+        alpha = int((1.0 - t) * 255)
+
+        if alpha > 0:
+            size = screen.get_size()
+            if (
+                self._overlay is None
+                or self._overlay.get_size() != size
+            ):
+                self._overlay = Surface(size, SRCALPHA)
+            self._overlay.fill((*self._color, alpha))
+            screen.blit(self._overlay, (0, 0))
+
+
+class Crossfade(_FadeBase):
+    """
+    Blends from source to target.
+    """
+
+    def __init__(self, easing: Callable[[float], float] = ease_in_out) -> None:
+        super().__init__(easing=easing)
+
+    def update(self, dt: float) -> None:
+        if self._done:
+            return
+        self._elapsed += dt
+        if self._elapsed >= self._duration:
+            self._elapsed = self._duration
+            self._done = True
+
+    def render(
+        self,
+        screen: Surface,
+        source: Surface | None = None,
+        target: Surface | None = None,
+    ) -> None:
+        t = self._easing(self._elapsed / self._duration) if self._duration > 0 else 1.0
+
+        if target is not None:
+            screen.blit(target, (0, 0))
+
+        if source is not None and t < 1.0:
+            alpha = int((1.0 - t) * 255)
+            size = screen.get_size()
+            if (
+                self._overlay is None
+                or self._overlay.get_size() != size
+            ):
+                self._overlay = Surface(size, SRCALPHA)
+            self._overlay.fill((0, 0, 0, 0))
+            self._overlay.blit(source, (0, 0))
+            self._overlay.set_alpha(alpha)
+            screen.blit(self._overlay, (0, 0))
+
+
+class Flash(_FadeBase):
+    """
+    Brief white (or colored) flash that fades quickly.
+    Default duration 0.15s.
+    """
+
+    def __init__(
+        self,
+        color: tuple[int, int, int] = (255, 255, 255),
+        easing: Callable[[float], float] = ease_in_out,
+    ) -> None:
+        super().__init__(color=color, easing=easing)
+
+    def start(self, duration: float | None = None) -> None:
+        super().start(0.15 if duration is None else duration)
+
+    def update(self, dt: float) -> None:
+        if self._done:
+            return
+        self._elapsed += dt
+        if self._elapsed >= self._duration:
+            self._elapsed = self._duration
+            self._done = True
+
+    def render(
+        self,
+        screen: Surface,
+        source: Surface | None = None,
+        target: Surface | None = None,
+    ) -> None:
+        if source is not None:
+            screen.blit(source, (0, 0))
+
+        t = self._easing(self._elapsed / self._duration) if self._duration > 0 else 1.0
+        alpha = int((1.0 - t) * 255)
+
+        if alpha > 0:
+            size = screen.get_size()
+            if (
+                self._overlay is None
+                or self._overlay.get_size() != size
+            ):
+                self._overlay = Surface(size, SRCALPHA)
+            self._overlay.fill((*self._color, alpha))
+            screen.blit(self._overlay, (0, 0))