pg-extended 0.0.1b1__tar.gz

pg_extended-0.0.1b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Saurabh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pg_extended-0.0.1b1/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: pg-extended
+Version: 0.0.1b1
+Summary: A lightweight 2d game engine built on top of pygame.
+Author-email: Saurabh Jadhav <pgextended.2025@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Saurabh262004/pg-extended
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pygame-ce
+Requires-Dist: pyperclip
+Requires-Dist: easygui
+Dynamic: license-file
+
+# pg-extended
+*A lightweight UI wrapper and window manager for pygame.*
+
+> [!WARNING]
+> - This library is in the early stages of development and may have many breaking changes in the future.  
+> - Some of the features are still to be refined and added.
+
+## Goal
+- Provide a dynamic, customizable, and intuitive system for building UI and game elements in pygame.
+- Handle repetitive UI / window management tasks for the user.
+- Eventually evolve into a small, modular game engine.
+
+---
+
+## Installation
+> [!IMPORTANT]
+> pip install support will be added later on.
+
+```
+git clone https://github.com/Saurabh262004/pg-extended.git 
+```
+
+Copy the `pg_extended/` folder into the root directory of your project.  
+Make sure that the folder name remains exactly `pg_extended/`.
+
+---
+
+# Example
+
+A simple example of how to initialize an empty window with pg_extended.
+
+```python
+from pg_extended import Window
+
+# create a window with "Demo pgx window" as the title with 1280x720 resolution
+app = Window("Demo pgx window", (1280, 720))
+
+# all the UI / Game setup can be done here
+
+# open the window
+app.openWindow()
+```
+
+> For more details, please checkout the [wiki page](../../wiki).
+
+---
+
+## [HVision](https://github.com/Saurabh262004/HVision)
+
+### A large project by me that uses pg_extended in a real environment.

pg_extended-0.0.1b1/README.md

@@ -0,0 +1,50 @@
+# pg-extended
+*A lightweight UI wrapper and window manager for pygame.*
+
+> [!WARNING]
+> - This library is in the early stages of development and may have many breaking changes in the future.  
+> - Some of the features are still to be refined and added.
+
+## Goal
+- Provide a dynamic, customizable, and intuitive system for building UI and game elements in pygame.
+- Handle repetitive UI / window management tasks for the user.
+- Eventually evolve into a small, modular game engine.
+
+---
+
+## Installation
+> [!IMPORTANT]
+> pip install support will be added later on.
+
+```
+git clone https://github.com/Saurabh262004/pg-extended.git 
+```
+
+Copy the `pg_extended/` folder into the root directory of your project.  
+Make sure that the folder name remains exactly `pg_extended/`.
+
+---
+
+# Example
+
+A simple example of how to initialize an empty window with pg_extended.
+
+```python
+from pg_extended import Window
+
+# create a window with "Demo pgx window" as the title with 1280x720 resolution
+app = Window("Demo pgx window", (1280, 720))
+
+# all the UI / Game setup can be done here
+
+# open the window
+app.openWindow()
+```
+
+> For more details, please checkout the [wiki page](../../wiki).
+
+---
+
+## [HVision](https://github.com/Saurabh262004/HVision)
+
+### A large project by me that uses pg_extended in a real environment.

pg_extended-0.0.1b1/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pg-extended"
+version = "0.0.1b1"
+description = "A lightweight 2d game engine built on top of pygame."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+  { name = "Saurabh Jadhav", email = "pgextended.2025@gmail.com" }
+]
+
+dependencies = [
+  "pygame-ce",
+  "pyperclip",
+  "easygui"
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.urls]
+Homepage = "https://github.com/Saurabh262004/pg-extended"

pg_extended-0.0.1b1/setup.cfg

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

pg_extended-0.0.1b1/src/pg_extended/Core/Base/AnimatedValue.py

@@ -0,0 +1,246 @@
+import time
+from copy import copy
+from pg_extended.Core.Base.DynamicValue import DynamicValue
+
+INTERPOLATION_TYPES = ['linear', 'easeIn', 'easeOut', 'easeInOut', 'custom']
+DEFAULT_POS_VALS = ['start', 'end']
+
+type valuesType = list[DynamicValue | AnimatedValue | int | float] | list[DynamicValue | AnimatedValue | int | float]
+
+class AnimatedValue:
+  def __init__(self, values: valuesType, duration: float, defaultPos: str = 'start', interpolation: str = 'linear', callback: callable = None, customInterpolation: callable = None):
+    if len(values) < 2:
+      raise ValueError("Animator requires a minimum of two values to animate between.")
+
+    if not interpolation in INTERPOLATION_TYPES:
+      raise ValueError(f'Invalid interpolation type: {interpolation}. Must be one of: {INTERPOLATION_TYPES}')
+
+    if interpolation == 'custom' and customInterpolation is None:
+      raise ValueError('Custom interpolation function must be provided when using "custom" interpolation type.')
+
+    if not defaultPos in DEFAULT_POS_VALS:
+      raise ValueError(f'Invalid defaultPos: {defaultPos}. Must be one of: {DEFAULT_POS_VALS}')
+
+    self.values = values
+    self.rawValues: list[int | float] = []
+    self.duration = duration
+    self.interpolation = interpolation
+    self.callback = callback
+    self.defaultPos = defaultPos
+
+    self.updateValues()
+
+    if self.defaultPos == 'start':
+      self.value = self.rawValues[0]
+    else:
+      self.value = self.rawValues[-1]
+
+    self.animStart: float = None
+    self.reverse: bool = False
+    self.repeats: int = 0
+    self.alternate: bool = False
+    self.hasPlayedOnce: bool = False
+    self.delay: int = 0
+
+    if self.interpolation == 'linear':
+      self.interpolationStep = self.linear
+    elif self.interpolation == 'easeIn':
+      self.interpolationStep = self.easeIn
+    elif self.interpolation == 'easeOut':
+      self.interpolationStep = self.easeOut
+    elif self.interpolation == 'easeInOut':
+      self.interpolationStep = self.easeInOut
+    elif self.interpolation == 'custom':
+      self.interpolationStep = customInterpolation
+
+  @staticmethod
+  def linear(start: float, end: float, t: float) -> float:
+    if t <= 0:
+      return start
+    elif t >= 1:
+      return end
+
+    return start + (end - start) * t
+
+  @staticmethod
+  def easeIn(start: float, end: float, t: float) -> float:
+    if t <= 0:
+      return start
+    elif t >= 1:
+      return end
+
+    t = t ** 2
+
+    return start + (end - start) * t
+
+  @staticmethod
+  def easeOut(start: float, end: float, t: float) -> float:
+    if t <= 0:
+      return start
+    elif t >= 1:
+      return end
+
+    t = 1 - (1 - t) ** 2
+
+    return start + (end - start) * t
+
+  @staticmethod
+  def easeInOut(start: float, end: float, t: float) -> float:
+    if t <= 0:
+      return start
+    elif t >= 1:
+      return end
+
+    t = t**3 * (t * (t * 6 - 15) + 10)
+
+    return start + (end - start) * t
+
+  # get raw values from animated / dynamic values
+  def updateValues(self):
+    self.rawValues = []
+
+    for value in self.values:
+      if isinstance(value, (DynamicValue, AnimatedValue)):
+        value.resolveValue()
+        self.rawValues.append(value.value)
+      else:
+        self.rawValues.append(value)
+
+  # get an interpolated value from normalized t
+  def interpolate(self, t: float):
+    if t <= 0:
+      return self.rawValues[0]
+    elif t >= 1:
+      return self.rawValues[-1]
+
+    processingVals = copy(self.rawValues)
+
+    while len(processingVals) > 1:
+      tmp = []
+
+      for i in range(len(processingVals) - 1):
+        tmp.append(
+          self.interpolationStep(processingVals[i], processingVals[i + 1], t)
+        )
+
+      processingVals = tmp
+
+    self.value = processingVals[0]
+
+  # calculate current animation time, get normalized t, call .interpolate() etc..
+  # most importantly this is the function you need to call to update the animated value
+  def resolveValue(self):
+    if self.animStart is None:
+      self.updateRestingPos()
+      return
+
+    elapsedTime = ((time.perf_counter() * 1000) - self.animStart) - self.delay
+
+    self.updateValues()
+
+    if elapsedTime >= self.duration:
+      self.finishAnim()
+    else:
+      if self.reverse:
+        t = 1 - (elapsedTime / self.duration)
+      else:
+        t = elapsedTime / self.duration
+
+      self.interpolate(t)
+
+  # handle animation ends, repeats, callbacks used by .resolveValue()
+  def finishAnim(self):
+    if self.reverse:
+      self.value = self.rawValues[0]
+    else:
+      self.value = self.rawValues[-1]
+
+    self.animStart = None
+
+    self.hasPlayedOnce = True
+
+    if self.repeats > 0:
+      self.repeats -= 1
+      self.trigger(self.reverse, self.repeats, self.alternate)
+      return None
+
+    if self.repeats == -1:
+      self.trigger(self.reverse, self.repeats, self.alternate)
+      return None
+
+    if self.callback is not None:
+      self.callback()
+
+  # updates the value to a default idle position when no animation is playing
+  def updateRestingPos(self):
+    self.updateValues()
+
+    A = self.hasPlayedOnce
+    B = self.defaultPos == 'start'
+    C = self.reverse
+
+    '''
+    this let's the system decide the resting position with only the default position when it hasn't ran yet
+    once it has ran, the reverse value also has an effect on the resting value
+
+    if self.hasPlayedOnce:
+      if self.defaultPos == 'start':
+        if self.reverse:
+          self.value = self.values[0].value
+        else:
+          self.value = self.values[-1].value
+      else:
+        if self.reverse:
+          self.value = self.values[-1].value
+        else:
+          self.value = self.values[0].value
+    else:
+      if self.defaultPos == 'start':
+        self.value = self.values[0].value
+      else:
+        self.value = self.values[-1].value
+
+    condition for choosing first value:
+    (A and B and C) or (A and not B and not C) or (not A and B)
+    condition for choosing last value:
+    (A and B and not C) or (A and not B and C) or (not A and not B)
+
+    compacted:
+    (A and (B == C)) or (not A and B)
+
+    maximum performance version:
+    (B and not A) or (A and (B == C))
+    '''
+
+    pickStart = (B and not A) or (A and (B == C))
+
+    self.value = self.rawValues[0] if pickStart else self.rawValues[-1]
+
+  # triggers animation
+  def trigger(self, reverse: bool = False, repeats: int = 0, alternate: bool = False, delay: int = 0):
+    self.animStart = time.perf_counter() * 1000
+
+    self.repeats = repeats
+    self.alternate = alternate
+    self.delay = delay
+
+    if self.hasPlayedOnce:
+      if self.alternate:
+        self.reverse = not self.reverse
+      else:
+        self.reverse = reverse
+    else:
+      self.reverse = reverse
+
+  # stops all animations, resets repeats and instantly snaps the value to a resting position
+  def terminate(self):
+    if self.animStart is None:
+      return None
+
+    self.animStart = None
+    self.repeats = 0
+
+    if self.reverse:
+      self.value = self.rawValues[0]
+    else:
+      self.value = self.rawValues[-1]

pg_extended-0.0.1b1/src/pg_extended/Core/Base/Callback.py

@@ -0,0 +1,57 @@
+from typing import Any
+from pg_extended.Core.Base import DynamicValue, AnimatedValue
+from pg_extended.Types import CallableLike
+
+class Callback:
+  def __init__(self, triggers: list[str] | tuple[str], func: CallableLike, staticArgs: dict[str, Any] = None, extraArgKeys: dict[str, str] = None):
+    self.triggers = triggers
+    self.func = func
+    self.staticArgs = staticArgs or {}
+    self.resolvedArgs = {}
+    self.extraArgKeys = extraArgKeys or {}
+    self.totalArgs = {}
+
+  def _setExtraArgs(self, args: dict[str, Any] = None):
+    args = args or {}
+
+    self.totalArgs = self.staticArgs.copy()
+
+    for key, value in args.items():
+      if key in self.extraArgKeys:
+        self.totalArgs[self.extraArgKeys[key]] = value
+
+  def resolveArgs(self):
+    self.resolvedArgs = {}
+
+    for key in self.totalArgs:
+      val = self.totalArgs[key]
+
+      if isinstance(val, (DynamicValue, AnimatedValue)):
+        val.resolveValue()
+        self.resolvedArgs[key] = val.value
+      else:
+        self.resolvedArgs[key] = val
+
+  def call(self, extraArgs: dict[str, Any] = None):
+    extraArgs = extraArgs or {}
+
+    self._setExtraArgs(extraArgs)
+
+    self.resolveArgs()
+
+    self.func(**self.resolvedArgs)
+
+class CallbackSet:
+  def __init__(self, callbacks: list[Callback] | tuple[Callback]):
+    self.callbacks = callbacks
+    self.callbacksDict = {}
+
+    for callback in self.callbacks:
+      for tgr in callback.triggers:
+        self.callbacksDict.setdefault(tgr, []).append(callback)
+
+  def call(self, trigger: str, extraArgs: dict[str, Any] = None):
+    if trigger not in self.callbacksDict: return None
+
+    for callback in self.callbacksDict[trigger]:
+      callback.call(extraArgs)

pg_extended-0.0.1b1/src/pg_extended/Core/Base/DynamicValue.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+from typing import Any
+from pg_extended.Types import CallableLike
+import types
+
+class DynamicValue:
+  def __init__(self, ref: Any, lookup: str | None = None, args: dict[str, Any] | None = None, percent: int | float | None = None):
+    self.reference = ref
+    self.lookup = lookup
+    self.args = args
+    self.percent = percent
+    self.value: Any = None
+    self.resolveValue: CallableLike = None
+
+    self.assignResolveMethod()
+
+    self.resolveValue()
+
+  def _IFPer(self):
+    self.value = self.reference / 100 * self.percent
+
+  def _dictLookup(self):
+    self.value = self.reference[self.lookup]
+
+  def _dictLookupPer(self):
+    self.value = self.reference[self.lookup] / 100 * self.percent
+
+  def _CV(self):
+    self.reference.resolveValue()
+    self.value = self.reference.value
+
+  def _CVPer(self):
+    self.reference.resolveValue()
+    self.value = self.reference.value / 100 * self.percent
+
+  def _call(self):
+    self.value = self.reference()
+
+  def _callPer(self):
+    self.value = self.reference() / 100 * self.percent
+
+  def _callArgs(self):
+    self.value = self.reference(**self.args)
+
+  def _callArgsPer(self):
+    self.value = self.reference(**self.args) / 100 * self.percent
+
+  def _objLookup(self):
+    self.value = getattr(self.reference, self.lookup)
+
+  def _objLookupPer(self):
+    self.value = getattr(self.reference, self.lookup) / 100 * self.percent
+
+  def _direct(self):
+    self.value = self.reference
+
+  def assignResolveMethod(self):
+    from pg_extended.Core.Base.AnimatedValue import AnimatedValue
+
+    # numbers with a percent value given
+    if isinstance(self.reference, (int, float)) and self.percent is not None:
+      self.resolveValue = self._IFPer
+
+    # dicts
+    elif isinstance(self.reference, dict) and self.lookup is not None:
+      if self.percent is None:
+        self.resolveValue = self._dictLookup
+      else:
+        self.resolveValue = self._dictLookupPer
+
+    # DV or AV
+    elif isinstance(self.reference, DynamicValue) or isinstance(self.reference, AnimatedValue):
+      if self.percent is None:
+        self.resolveValue = self._CV
+      else:
+        self.resolveValue = self._CVPer
+
+    # callable
+    elif isinstance(self.reference, (types.FunctionType | types.BuiltinFunctionType | types.MethodType)):
+      if self.args is None:
+        if self.percent is None:
+          self.resolveValue = self._call
+        else:
+          self.resolveValue = self._callPer
+      else:
+        if self.percent is None:
+          self.resolveValue = self._callArgs
+        else:
+          self.resolveValue = self._callArgsPer
+
+    # none of the above and lookup is provided, assume it's a class + attribute
+    elif isinstance(self.lookup, str):
+      if self.percent is None:
+        self.resolveValue = self._objLookup
+      else:
+        self.resolveValue = self._objLookupPer
+
+    # dump everything else into direct
+    else:
+      self.resolveValue = self._direct

pg_extended-0.0.1b1/src/pg_extended/Core/Base/__init__.py

@@ -0,0 +1,3 @@
+from pg_extended.Core.Base.DynamicValue import DynamicValue
+from pg_extended.Core.Base.AnimatedValue import AnimatedValue
+from pg_extended.Core.Base.Callback import Callback, CallbackSet

pg_extended-0.0.1b1/src/pg_extended/Core/Composites/CircleArea.py

@@ -0,0 +1,33 @@
+from pg_extended.Core.Base.DynamicValue import DynamicValue
+from pg_extended.Core.Base.AnimatedValue import AnimatedValue
+
+type NumValue = DynamicValue | AnimatedValue | int | float
+
+class CircleArea:
+  def __init__(self, dimensions: dict[str, NumValue]):
+    self.dimensions = dimensions
+
+    if not len(self.dimensions) == 3:
+      raise ValueError(f'dimensions must contain 3 Dimension objects, received: {len(self.dimensions)}')
+
+    for key in ('x', 'y', 'radius'):
+      if not key in self.dimensions:
+        raise ValueError('dimensions must contain all of the following keys: \'x\', \'y\', \'radius\'')
+
+    self.x: int | float
+    self.y: int | float
+    self.radius: int | float
+
+    self.update()
+
+  def getDimValue(self, key: str) -> int | float:
+    return self.dimensions[key].value if isinstance(self.dimensions[key], (DynamicValue, AnimatedValue)) else self.dimensions[key]
+
+  def update(self):
+    for key in self.dimensions:
+      if isinstance(self.dimensions[key], (DynamicValue, AnimatedValue)):
+        self.dimensions[key].resolveValue()
+
+    self.x = self.getDimValue("x")
+    self.y = self.getDimValue("y")
+    self.radius = self.getDimValue("radius")

pg_extended-0.0.1b1/src/pg_extended/Core/Composites/RectArea.py

@@ -0,0 +1,40 @@
+import pygame as pg
+from pg_extended.Core.Base.DynamicValue import DynamicValue
+from pg_extended.Core.Base.AnimatedValue import AnimatedValue
+
+type NumValue = DynamicValue | AnimatedValue | int | float
+
+class RectArea:
+  def __init__(self, dimensions: dict[str, NumValue]):
+    self.dimensions: dict[str, NumValue] = dimensions
+
+    if not len(self.dimensions) == 4:
+      raise ValueError(f'dimensions must contain 4 Dimension objects, received: {len(self.dimensions)}')
+
+    for key in ('x', 'y', 'width', 'height'):
+      if not key in self.dimensions:
+        raise ValueError('dimensions must contain all of the following keys: \'x\', \'y\', \'width\' \'height\'')
+
+    self.x: int | float
+    self.y: int | float
+    self.width: int | float
+    self.height: int | float
+
+    self.rect: pg.Rect = pg.Rect(0, 0, 0, 0)
+
+    self.update()
+
+  def getDimValue(self, key: str) -> int | float:
+    return self.dimensions[key].value if isinstance(self.dimensions[key], (DynamicValue, AnimatedValue)) else self.dimensions[key]
+
+  def update(self):
+    for key in self.dimensions:
+      if isinstance(self.dimensions[key], (DynamicValue, AnimatedValue)):
+        self.dimensions[key].resolveValue()
+
+    self.x = self.getDimValue("x")
+    self.y = self.getDimValue("y")
+    self.width = self.getDimValue("width")
+    self.height = self.getDimValue("height")
+    
+    self.rect.update(self.x, self.y, self.width, self.height)

pg_extended-0.0.1b1/src/pg_extended/Core/Composites/__init__.py

@@ -0,0 +1,2 @@
+from pg_extended.Core.Composites.RectArea import RectArea
+from pg_extended.Core.Composites.CircleArea import CircleArea

pg_extended-0.0.1b1/src/pg_extended/Core/__init__.py

@@ -0,0 +1,5 @@
+from pg_extended.Core import Composites
+from pg_extended.Core import Base
+
+from pg_extended.Core.Composites import *
+from pg_extended.Core.Base import *