pygkit 1.0.8__tar.gz → 2.1.0__tar.gz

{pygkit-1.0.8 → pygkit-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pygkit
-Version: 1.0.8
+Version: 2.1.0
 Summary: General-purpose Pygame CE runtime kit: UI widgets, audio, timers, interpolation, and more.
 Author: pygkit contributors
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -694,6 +694,15 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pygame-ce>=2.5
+Provides-Extra: ui
+Provides-Extra: audio
+Provides-Extra: animation
+Provides-Extra: lighting
+Provides-Extra: transitions
+Provides-Extra: inventory
+Provides-Extra: parallax
+Provides-Extra: all
+Requires-Dist: pygkit[animation,audio,inventory,lighting,parallax,transitions,ui]; extra == "all"
 Dynamic: license-file
 
 # pygkit
@@ -708,11 +717,11 @@ import pygkit
 
 ## Features
 
-- **UI**: Box-model widgets with plugin compositing — progress bars, cooldown overlays, containers, dialog system
+- **UI**: Box-model widgets with plugin compositing — progress bars, cooldown overlays, containers, dialog system, buttons, menubar container, anchor/row/grid placement helpers
 - **Animation**: Multi-state `AnimationPlayer` where every state owns its own spritesheet — mixed image sizes and grids (e.g. `idle_spritesheet.png` vs `run_spritesheet.png`) in one player; pure image API, no JSON
 - **Dialog**: Typewriter effect with customizable speeds, speaker names, and progress indicators
 - **Inventory**: Grid-based item management with stacking, weight tracking, events, and serialization
-- **Audio**: SoundManager with channel pools and explicit targeting
+- **Audio**: SoundManager with channel pools, kind/key addressing, volume buses, fades
 - **Lighting**: low-resolution light map pipeline (`LightMap`), point lights
   with flicker, wind-reactive `DynamicLight` flames, and cone `Spotlight` —
   full RGB/RGBA blend modes, allocation-free per frame
@@ -722,5 +731,13 @@ import pygkit
 ## Installation
 
 ```bash
-pip install pygkit
+pip install pygkit            # core: signals, utils, protocols
+pip install "pygkit[ui]"      # widgets, dialog, cooldowns
+pip install "pygkit[all]"     # everything
 ```
+
+Available extras: `ui`, `audio`, `animation`, `lighting`,
+`transitions`, `inventory`, `parallax`, `all`. `import pygkit` alone loads
+core only; subsystems load lazily on first use.
+
+> Extra: lightning idea was extended version of [https://www.youtube.com/watch?v=LN7u20H7zK4](https://www.youtube.com/watch?v=LN7u20H7zK4) which was my first attempt of making lightning after learning blend modes.

{pygkit-1.0.8 → pygkit-2.1.0}/README.md

@@ -10,11 +10,11 @@ import pygkit
 
 ## Features
 
-- **UI**: Box-model widgets with plugin compositing — progress bars, cooldown overlays, containers, dialog system
+- **UI**: Box-model widgets with plugin compositing — progress bars, cooldown overlays, containers, dialog system, buttons, menubar container, anchor/row/grid placement helpers
 - **Animation**: Multi-state `AnimationPlayer` where every state owns its own spritesheet — mixed image sizes and grids (e.g. `idle_spritesheet.png` vs `run_spritesheet.png`) in one player; pure image API, no JSON
 - **Dialog**: Typewriter effect with customizable speeds, speaker names, and progress indicators
 - **Inventory**: Grid-based item management with stacking, weight tracking, events, and serialization
-- **Audio**: SoundManager with channel pools and explicit targeting
+- **Audio**: SoundManager with channel pools, kind/key addressing, volume buses, fades
 - **Lighting**: low-resolution light map pipeline (`LightMap`), point lights
   with flicker, wind-reactive `DynamicLight` flames, and cone `Spotlight` —
   full RGB/RGBA blend modes, allocation-free per frame
@@ -24,5 +24,13 @@ import pygkit
 ## Installation
 
 ```bash
-pip install pygkit
+pip install pygkit            # core: signals, utils, protocols
+pip install "pygkit[ui]"      # widgets, dialog, cooldowns
+pip install "pygkit[all]"     # everything
 ```
+
+Available extras: `ui`, `audio`, `animation`, `lighting`,
+`transitions`, `inventory`, `parallax`, `all`. `import pygkit` alone loads
+core only; subsystems load lazily on first use.
+
+> Extra: lightning idea was extended version of [https://www.youtube.com/watch?v=LN7u20H7zK4](https://www.youtube.com/watch?v=LN7u20H7zK4) which was my first attempt of making lightning after learning blend modes.

{pygkit-1.0.8 → pygkit-2.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pygkit"
-version = "1.0.8"
+version = "2.1.0"
 description = "General-purpose Pygame CE runtime kit: UI widgets, audio, timers, interpolation, and more."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -26,6 +26,22 @@ classifiers = [
   "Topic :: Software Development :: Libraries",
 ]
 
+[project.optional-dependencies]
+# One extra per subsystem. Empty for now: every subsystem is pure
+# pygame-ce + stdlib. Slots are reserved for future speedups
+# (lighting color math -> numpy, sprite pack -> pillow) without
+# taxing core installs.
+ui = []
+audio = []
+animation = []
+lighting = []
+transitions = []
+inventory = []
+parallax = []
+all = [
+  "pygkit[ui, audio, animation, lighting, transitions, inventory, parallax]",
+]
+
 [project.urls]
 Homepage = "https://github.com/FluffyBrudy/pygkit"
 Repository = "https://github.com/FluffyBrudy/pygkit"

pygkit-2.1.0/src/pygkit/__init__.py

@@ -0,0 +1,231 @@
+"""pygkit - Pygame CE runtime kit.
+
+Core (signals, utils, protocols) imports eagerly. Subsystems load
+lazily on first attribute use, so ``import pygkit`` stays cheap::
+
+    pip install pygkit          # core only
+    pip install "pygkit[ui]"    # + widgets, dialog, cooldowns
+    pip install "pygkit[all]"   # everything
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+from .protocols import Clickable, Drawable, Renderable, UIElement, Updateable, Widget
+from .signals import Signal, SignalBus, signal
+from .utils import (
+    SimpleInterpolation,
+    Timer,
+    ease_in,
+    ease_in_out,
+    ease_out,
+    fit,
+    lerp,
+    load_font,
+    outline,
+    render_multiline,
+    shadow,
+    smoothstep,
+    wrap,
+)
+
+_LAZY_ATTRS: dict[str, str] = {
+    "SoundManager": "audio",
+    "SFX_CHANNELS": "audio",
+    "DEFAULT_SFX_CHANNELS": "audio",
+    "ParallaxBackground": "parallax",
+    "ParallaxLayer": "parallax",
+    "Camera2D": "parallax",
+    "AnimationPlayer": "animation",
+    "AnimationSheet": "animation",
+    "PackOptions": "animation",
+    "pack_spritesheet": "animation",
+    "LightMap": "lighting",
+    "PointLight": "lighting",
+    "Spotlight": "lighting",
+    "DynamicLight": "lighting",
+    "glow_sprite": "lighting",
+    "spotlight_sprite": "lighting",
+    "dynamic_glow_sprite": "lighting",
+    "clear_sprite_cache": "lighting",
+    "RGB_ADD": "lighting",
+    "RGB_SUB": "lighting",
+    "RGB_MULT": "lighting",
+    "RGB_MIN": "lighting",
+    "RGB_MAX": "lighting",
+    "RGBA_ADD": "lighting",
+    "RGBA_SUB": "lighting",
+    "RGBA_MULT": "lighting",
+    "RGBA_MIN": "lighting",
+    "RGBA_MAX": "lighting",
+    "LIGHT_ADD": "lighting",
+    "SCENE_MULT": "lighting",
+    "TransitionRunner": "transitions",
+    "TransitionState": "transitions",
+    "FadeToBlack": "transitions",
+    "FadeFromBlack": "transitions",
+    "Crossfade": "transitions",
+    "Flash": "transitions",
+    "IrisIn": "transitions",
+    "IrisOut": "transitions",
+    "Slide": "transitions",
+    "PixelDissolve": "transitions",
+    "Shake": "transitions",
+    "Container": "ui",
+    "CooldownOverlay": "ui",
+    "ProgressBarUI": "ui",
+    "UIBase": "ui",
+    "UIOptions": "ui",
+    "BoxModel": "ui",
+    "BoxModelResult": "ui",
+    "generate_box_model": "ui",
+    "DialogBox": "ui",
+    "DialogConfig": "ui",
+    "DialogColors": "ui",
+    "DialogLine": "ui",
+    "TypewriterSpeed": "ui",
+    "Button": "ui",
+    "ButtonStyle": "ui",
+    "Menubar": "ui",
+    "ANCHORS": "ui",
+    "anchor_point": "ui",
+    "place": "ui",
+    "row": "ui",
+    "column": "ui",
+    "grid": "ui",
+    "ItemData": "inventory",
+    "InventoryConfig": "inventory",
+    "ItemStack": "inventory",
+    "InventoryEvent": "inventory",
+    "RARITY_COLORS": "inventory",
+    "DEFAULT_INVENTORY_CONFIG": "inventory",
+    "Inventory": "inventory",
+    "AssetCache": "inventory",
+    "get_cache": "inventory",
+    "generate_procedural_icon": "inventory",
+    "render_quantity_text": "inventory",
+    "Tooltip": "inventory",
+    "DragDropState": "inventory",
+    "InventoryWidget": "inventory",
+    "InventoryManager": "inventory",
+}
+
+__all__ = [
+    "SoundManager",
+    "SFX_CHANNELS",
+    "DEFAULT_SFX_CHANNELS",
+    "ParallaxBackground",
+    "ParallaxLayer",
+    "Camera2D",
+    "AnimationPlayer",
+    "AnimationSheet",
+    "PackOptions",
+    "pack_spritesheet",
+    "LightMap",
+    "PointLight",
+    "Spotlight",
+    "DynamicLight",
+    "glow_sprite",
+    "spotlight_sprite",
+    "dynamic_glow_sprite",
+    "clear_sprite_cache",
+    "RGB_ADD",
+    "RGB_SUB",
+    "RGB_MULT",
+    "RGB_MIN",
+    "RGB_MAX",
+    "RGBA_ADD",
+    "RGBA_SUB",
+    "RGBA_MULT",
+    "RGBA_MIN",
+    "RGBA_MAX",
+    "LIGHT_ADD",
+    "SCENE_MULT",
+    "TransitionRunner",
+    "TransitionState",
+    "FadeToBlack",
+    "FadeFromBlack",
+    "Crossfade",
+    "Flash",
+    "IrisIn",
+    "IrisOut",
+    "Slide",
+    "PixelDissolve",
+    "Shake",
+    "Container",
+    "CooldownOverlay",
+    "ProgressBarUI",
+    "UIBase",
+    "UIOptions",
+    "BoxModel",
+    "BoxModelResult",
+    "generate_box_model",
+    "DialogBox",
+    "DialogConfig",
+    "DialogColors",
+    "DialogLine",
+    "TypewriterSpeed",
+    "Button",
+    "ButtonStyle",
+    "Menubar",
+    "ANCHORS",
+    "anchor_point",
+    "place",
+    "row",
+    "column",
+    "grid",
+    "ItemData",
+    "InventoryConfig",
+    "ItemStack",
+    "InventoryEvent",
+    "RARITY_COLORS",
+    "DEFAULT_INVENTORY_CONFIG",
+    "Inventory",
+    "AssetCache",
+    "get_cache",
+    "generate_procedural_icon",
+    "render_quantity_text",
+    "Tooltip",
+    "DragDropState",
+    "InventoryWidget",
+    "InventoryManager",
+    "SimpleInterpolation",
+    "Timer",
+    "lerp",
+    "smoothstep",
+    "ease_in_out",
+    "ease_out",
+    "ease_in",
+    "load_font",
+    "outline",
+    "shadow",
+    "wrap",
+    "render_multiline",
+    "fit",
+    "Signal",
+    "SignalBus",
+    "signal",
+    "Renderable",
+    "UIElement",
+    "Drawable",
+    "Updateable",
+    "Clickable",
+    "Widget",
+]
+
+
+def __getattr__(name: str) -> Any:
+    try:
+        sub = _LAZY_ATTRS[name]
+    except KeyError:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+    module = importlib.import_module(f"{__name__}.{sub}")
+    value = getattr(module, name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

{pygkit-1.0.8 → pygkit-2.1.0}/src/pygkit/animation/player.py

@@ -1,10 +1,13 @@
 from __future__ import annotations
 
+import math
 from dataclasses import dataclass
 from typing import Callable
 
 from .sheet import AnimationSheet
 
+_UNSET: object = object()
+
 
 @dataclass
 class _State:
@@ -19,7 +22,7 @@ class AnimationPlayer:
 
     States are registered lazily via :meth:`play`; sheets may differ freely in
     pixel size and grid layout between states. Playback is time-based: feed
-    ``update(dt_ms)`` each frame and blit ``image``.
+    ``update(dt)`` each frame with delta time in seconds and blit ``image``.
     """
 
     __slots__ = (
@@ -89,13 +92,15 @@ class AnimationPlayer:
         *,
         fps: float | None = None,
         loop: bool | None = None,
-        on_finish: Callable[[], None] | None = None,
+        on_finish: Callable[[], None] | None | object = _UNSET,
+        restart: bool = False,
     ) -> None:
         """Switch to *name*, registering the state on first use.
 
         Registration requires *sheet*; omitted options fall back to the
         player defaults given at construction. Calling ``play`` for the state
-        already playing does not restart it — use :meth:`reset`.
+        already playing does not restart it unless ``restart`` is true.
+        Pass ``on_finish=None`` explicitly to clear a default callback.
         """
         if name not in self._states:
             if sheet is None:
@@ -106,37 +111,37 @@ class AnimationPlayer:
                 sheet=sheet,
                 fps=float(resolved_fps),
                 loop=self._default_loop if loop is None else bool(loop),
-                on_finish=self._default_on_finish if on_finish is None else on_finish,
+                on_finish=self._default_on_finish if on_finish is _UNSET else on_finish,
             )
 
-        if name == self._state_name:
+        if name == self._state_name and not restart:
             return
         self._state_name = name
         self.reset()
 
-    def update(self, dt_ms: float) -> None:
-        """Advance playback by *dt_ms* milliseconds of wall time."""
+    def update(self, dt: float) -> None:
+        """Advance playback by *dt* seconds."""
         if self._paused or self._state_name is None or self._finished:
             return
+        if not math.isfinite(dt) or dt < 0:
+            dt = 0.0
         state = self._states[self._state_name]
         frame_count = state.sheet.frame_count
-        frame_duration = 1000.0 / state.fps
-        self._elapsed_in_frame += max(0.0, dt_ms)
-        while self._elapsed_in_frame >= frame_duration:
-            self._elapsed_in_frame -= frame_duration
-            next_index = self._frame_index + 1
-            if next_index < frame_count:
-                self._frame_index = next_index
-                continue
-            if state.loop:
-                self._frame_index = 0
-            else:
-                self._frame_index = frame_count - 1
-                self._elapsed_in_frame = 0.0
-                self._finished = True
-                if state.on_finish is not None:
-                    state.on_finish()
-                break
+        frame_duration = 1.0 / state.fps
+        steps, self._elapsed_in_frame = divmod(self._elapsed_in_frame + dt, frame_duration)
+        steps = int(steps)
+        if steps <= 0:
+            return
+        if state.loop:
+            self._frame_index = (self._frame_index + steps) % frame_count
+        elif self._frame_index + steps >= frame_count:
+            self._frame_index = frame_count - 1
+            self._elapsed_in_frame = 0.0
+            self._finished = True
+            if state.on_finish is not None:
+                state.on_finish()
+        else:
+            self._frame_index += steps
 
     def pause(self) -> None:
         self._paused = True

pygkit-2.1.0/src/pygkit/audio/__init__.py

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