system-b 1.1.4__tar.gz

system_b-1.1.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Bee Hall
+
+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.

system_b-1.1.4/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: system-b
+Version: 1.1.4
+Summary: A pygame engine for common game operations like vector math and maintaining events in the game loop
+Author-email: Bee Hall <bhall1224@gmail.com>
+Project-URL: Homepage, https://gitlab.com/bhall/game-utils
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: <=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pygame
+Requires-Dist: numpy
+Dynamic: license-file
+
+# Game Utils
+
+>1.1.4
+
+## `game-utils` is a pygame engine.  The engine includes modules to facilitate boilerplate game operations. 
+
+### Requirements
+
+**Dependences:**
+- pygame
+- numpy
+
+**Demo Game**
+
+Run: `python -m game_utils.demo` or `python -m game_utils.toolkit --demo` to play the demo bouncy ball game!
+
+Run: `python -m game_utils.toolkit --copy` to copy the sample project to your directory!
+
+---
+
+## See Also...
+
+<p><b>My ongoing game projects!</b></p>
+
+- [GitLab](https://gitlab.com/bhall)

system_b-1.1.4/README.md

@@ -0,0 +1,25 @@
+# Game Utils
+
+>1.1.4
+
+## `game-utils` is a pygame engine.  The engine includes modules to facilitate boilerplate game operations. 
+
+### Requirements
+
+**Dependences:**
+- pygame
+- numpy
+
+**Demo Game**
+
+Run: `python -m game_utils.demo` or `python -m game_utils.toolkit --demo` to play the demo bouncy ball game!
+
+Run: `python -m game_utils.toolkit --copy` to copy the sample project to your directory!
+
+---
+
+## See Also...
+
+<p><b>My ongoing game projects!</b></p>
+
+- [GitLab](https://gitlab.com/bhall)

system_b-1.1.4/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "system-b"
+version = "1.1.4"
+authors = [
+    { name="Bee Hall", email="bhall1224@gmail.com" },
+]
+description = "A pygame engine for common game operations like vector math and maintaining events in the game loop"
+readme = "README.md"
+requires-python = "<=3.13"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "pygame",
+    "numpy"
+]
+
+[project.urls]
+"Homepage" = "https://gitlab.com/bhall/game-utils"
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"

system_b-1.1.4/setup.cfg

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

system_b-1.1.4/src/system_b/controller/controller.py

@@ -0,0 +1,74 @@
+from abc import abstractmethod
+
+
+from pygame import Vector2, key, joystick
+
+
+class Controller:
+    def __init__(self, directions: list[int]):
+        self._directions = directions
+
+    @abstractmethod
+    def direction(self, scalar) -> Vector2:
+        raise NotImplementedError
+
+    @abstractmethod
+    def action(self, index) -> bool:
+        raise NotImplementedError
+
+
+class KeyboardController(Controller):
+    def __init__(self, directions, actions):
+        """Provide directions up, down, left, and right, in that order; and provide actions
+
+        Args:
+            directions (list[int]): ex. [pygame.K_w, pygame.K_s ...]
+            actions (list[int]): ex. [pygame.K_SPACE, pygame.K_ESCAPE ...]
+        """
+        super.__init__(directions)
+        self._actions = actions
+
+
+class DefaultKeyboardController(KeyboardController):
+    def __init__(self, directions, actions):
+        super().__init__(directions, actions)
+
+    def direction(self, scalar=1):
+        u, d, l, r = (key.get_pressed()[i] for i in self._directions[:4])
+
+        return Vector2(r - l, u - d) * scalar
+
+    def action(self, index):
+        return self._actions[index]
+
+
+class JoystickController(Controller):
+    def __init__(self, id: int, directions):
+        """Provide directions up, down, left, and right, in that order; and provide actions
+
+        Args:
+            directions (list[int]): ex. [0, 1 ...]
+            actions (list[int]): ex. [0, 1 ...]
+        """
+        super.__init__(directions)
+        if not joystick.get_init():
+            joystick.init()
+
+        self._joystick = joystick.Joystick(id)
+
+
+class DefaultJoystickController(JoystickController):
+    def __init__(self, id, directions):
+        super().__init__(id, directions)
+
+    def direction(self, scalar):
+        x = self._joystick.get_axis(self._directions[0])
+        y = self._joystick.get_axis(self._directions[1])
+
+        return Vector2(x, y) * scalar
+
+    def rotation(self):
+        return self._joystick.get_axis(2)
+
+    def action(self, index):
+        return self._joystick.get_button(index)

system_b-1.1.4/src/system_b/demo/__main__.py

@@ -0,0 +1,4 @@
+from .demo import main
+
+if __name__ == "__main__":
+    main()

system_b-1.1.4/src/system_b/demo/demo.py

@@ -0,0 +1,268 @@
+#!/usr/bin/env python3
+
+from pygame import Rect, Surface, Vector2
+from pygame import display, draw, sprite, key
+from pygame import K_DOWN, K_RIGHT, K_ESCAPE, K_UP, KEYDOWN, K_LEFT
+from system_b.game import SpriteGame
+from system_b.physics import PhysicsBody
+from system_b.screen import ScreenReference
+from system_b.sprites import PhysicsSprite
+from system_b.math.vector_utils import apply_vector_actions, get_random_vector
+
+
+class BouncyBallPlayer(PhysicsSprite):
+    """A PlayerSprite is a subclass of PhysicsSprite.  It features
+    a PhysicsBody and also a Controller reference.  Here you define logic
+    for what the controller actions do to the player sprite over time"""
+
+    def __init__(
+        self,
+        image: Surface,
+        position: Vector2,
+        physics_body: PhysicsBody,
+        color: str = "indigo",
+        boundaries: Rect | None = None,
+        id: int = 0,
+    ):
+        super().__init__(image, position, physics_body, boundaries, id)
+        self.color = color
+        # lock for collision logic - freezes if calculated at every loop
+        self.collided = False
+
+    def update(self, dt: float):
+        # sync position and physics body
+        self.physics_body.move(dt)
+
+        # bound position with physics body
+        self._update_pos(
+            self.physics_body.position,
+            xbounds=self._bounds_x,
+            ybounds=self._bounds_y,
+        )
+
+    def _bounds_x(self):
+        self.physics_body.velociy = apply_vector_actions(
+            self.physics_body.velociy,
+            lambda v: Vector2(0, v.y),
+        )
+
+    def _bounds_y(self):
+        self.physics_body.velociy = apply_vector_actions(
+            self.physics_body.velociy,
+            lambda v: Vector2(v.x, 0),
+        )
+
+
+class BouncyBallPuck(PhysicsSprite):
+    """This bit probably looks complicated, and it is :)
+    PhysicsSprite is subclass of GameSprite that features a PhysicsBody.
+    Here we define the logic for what the sprite will do over time"""
+
+    def __init__(
+        self,
+        image: Surface,
+        position: Vector2,
+        physics_body: PhysicsBody,
+        color: str = "blue",
+        boundaries: Rect | None = None,
+        id: int = 0,
+        speed: float = 50,
+    ):
+        super().__init__(image, position, physics_body, boundaries, id)
+        self.color = color
+        self.speed = speed
+        self.physics_body.velociy = get_random_vector(speed)
+        self.start_position = Vector2.copy(position)
+
+    def update(self, dt: float):
+        # sync position and physics body
+        self.physics_body.move(dt)
+        # bound positions
+        self._update_pos(
+            self.physics_body.position,
+            xbounds=self.__bounds_x,
+            ybounds=self.__bounds_y,
+        )
+
+    def __bounds_x(self):
+        self.physics_body.velociy = (
+            apply_vector_actions(
+                self.physics_body.velociy, lambda v: Vector2(-v.x, v.y)
+            )
+            * self.physics_body.elasticity
+        )
+
+    def __bounds_y(self):
+        self.physics_body.velociy = (
+            apply_vector_actions(
+                self.physics_body.velociy,
+                lambda v: Vector2(v.x, -v.y),
+            )
+            * self.physics_body.elasticity
+        )
+
+
+class BouncyBallScreen(ScreenReference):
+    """Anything to do with screen activity"""
+
+    def __init__(
+        self,
+        player: BouncyBallPlayer,
+        puck: BouncyBallPuck,
+        width=0,
+        height=0,
+        frames_per_second=60,
+        bg_color=None,
+        bg_image=None,
+    ):
+        super().__init__(
+            width=width,
+            height=height,
+            frames_per_second=frames_per_second,
+            bg_color=bg_color,
+            bg_image=bg_image,
+        )
+        self.puck = puck
+        self.player = player
+
+    def update_screen(self):
+        # DRAW THE TABLE
+        draw.rect(
+            surface=self.screen,
+            color=self.bg_color or "black",
+            rect=(0, 0, self.width, self.height),
+            border_radius=15,
+        )
+        # DRAW PLAYER
+        draw.circle(
+            self.screen,
+            self.player.color,
+            self.player.position,
+            self.player.rect.h,
+        )
+
+        # DRAW PUCK
+        draw.circle(
+            self.screen,
+            self.puck.color,
+            self.puck.position,
+            self.puck.rect.h,
+        )
+
+
+class BouncyBall(SpriteGame):
+    """This is where high-level game logic goes
+    Think of this as the game-loop layer of the
+    application
+    """
+
+    def __init__(self, ctrl_speed, screen_ref, player_sprites, other_sprites):
+        # configure sprites
+        super().__init__(screen_ref, player_sprites, other_sprites)
+        display.set_caption("Game Utils Demo Game")
+        self.puck: BouncyBallPuck = self.other_sprites_group.sprites()[0]
+        self.player: BouncyBallPlayer = self.player_sprites[0]
+        self.ctrl_speed = ctrl_speed
+
+    def events(self, event):
+        if event.type == KEYDOWN:
+            # print(f"Key pressed: {event.key}")
+            if key.get_pressed()[K_ESCAPE]:
+                self._running = False
+
+            accel = (
+                Vector2(
+                    (key.get_pressed()[K_RIGHT] - key.get_pressed()[K_LEFT]),
+                    (key.get_pressed()[K_DOWN] - key.get_pressed()[K_UP]),
+                )
+                * self.ctrl_speed
+            )
+
+            self.player.physics_body.force(accel, self._screen_ref.get_delta_time())
+
+    def update(self):
+        """This method is required in a Game implementation.
+        Here is where the game loop logic will go.  This will
+        be called once per game loop"""
+        dt = self._screen_ref.get_delta_time()
+
+        self.player.update(dt)
+        self.puck.update(dt)
+
+        if sprite.collide_circle(self.player, self.puck):
+            # lock out of collision logic so it doesn't freeze lol
+            if not self.player.collided:
+                self.player.physics_body.on_collide(self.puck.physics_body)
+                self.puck.physics_body.on_collide(self.player.physics_body)
+                self.player.collided = True
+        else:
+            self.player.collided = False
+
+
+def main():
+    """configurations kept in a separate file
+    can make it easy to change things at this
+    orchestration level.
+    Play around with these input paramters and see what you can get it to do!"""
+    input_params = {
+        "player": {
+            "color": "darkred",
+            "physics_body": {"mass": 4, "friction": 0.002, "elasticity": 0},
+        },
+        "puck": {
+            "color": "midnightblue",
+            "physics_body": {"mass": 0.5, "friction": 0, "elasticity": 0},
+        },
+        "controller": {"speed": 1500.0},
+        "table": {"color": "firebrick"},
+        "mode": "DEBUG",
+        "screen": {"width": 1280},
+    }
+
+    # properties
+    table_color = input_params["table"]["color"]
+    ctrl_speed = input_params["controller"]["speed"]
+    player_physics = input_params["player"]["physics_body"]
+    player_color = input_params["player"]["color"]
+    puck_physics = input_params["puck"]["physics_body"]
+    puck_color = input_params["puck"]["color"]
+    screen_w = input_params["screen"]["width"]
+    screen_h = screen_w / 16 * 9  # screen["height"]
+    puck_size = screen_h / 9 / 2
+
+    # configure sprites
+    player = BouncyBallPlayer(
+        image=Surface((puck_size, puck_size)),
+        position=Vector2(screen_w / 2, screen_h / 2),
+        physics_body=PhysicsBody(
+            mass=player_physics["mass"],
+            friction=player_physics["friction"],
+            elasticity=player_physics["elasticity"],
+        ),
+        boundaries=Rect(screen_w, 0, screen_h, 0),
+        color=player_color,
+    )
+
+    puck = BouncyBallPuck(
+        image=Surface((puck_size, puck_size)),
+        position=Vector2(screen_w / 4, screen_h / 4),
+        boundaries=Rect(screen_w, 0, screen_h, 0),
+        physics_body=PhysicsBody(
+            mass=puck_physics["mass"],
+            friction=puck_physics["friction"],
+            elasticity=puck_physics["elasticity"],
+        ),
+        color=puck_color,
+    )
+
+    # screen settings and configurations
+    settings = BouncyBallScreen(
+        player, puck, width=screen_w, height=screen_h, bg_color=table_color
+    )
+
+    # load sprites and configurations
+    game = BouncyBall(ctrl_speed, settings, [player], [puck])
+
+    print("Starting game...")
+    game.run()
+    print("Game quit")

system_b-1.1.4/src/system_b/exceptions/game_exception.py

@@ -0,0 +1,4 @@
+
+
+# to see when an exception is caused by my foolery
+GameError = Exception

system_b-1.1.4/src/system_b/game/__init__.py

@@ -0,0 +1,4 @@
+from .game import (
+    Game,
+    SpriteGame
+)

system_b-1.1.4/src/system_b/game/game.py

@@ -0,0 +1,82 @@
+from abc import abstractmethod
+
+import pygame
+
+from system_b.screen import ScreenReference
+from system_b.sprites import GameSprite
+
+
+class Game:
+    """Game class defines high-level game logic. This class includes a run method, which controls the game loop.
+    User is required to implement abstract methods self.update() and self.events(), which is invoked within self.run()
+    """
+
+    def __init__(self, screen_ref: ScreenReference | None = None):
+        """High level game orchestrations
+
+        Args:
+            screen_ref (ScreenReference): Any screen settings
+        """
+        self._running = False
+        self._screen_ref = screen_ref
+
+    def run(self):
+        """Runs and maintains the game loop and clock. Updates the screen and invokes any handlers
+        Invokes pygame.init(), pygame.quit() when pygame.QUIT event is reached
+        """
+        pygame.init()
+        self._running = True
+        while self._running:
+            self.update()
+            if self._screen_ref is not None:
+                self._screen_ref.update_screen()
+                pygame.display.flip()
+            for event in pygame.event.get():
+                if event.type == pygame.QUIT:
+                    self._running = False
+                self.events(event)
+
+        pygame.quit()
+
+    @abstractmethod
+    def events(self, event: pygame.event.Event):
+        """Define custom event handlers.  Optional.  Called once per game loop
+
+        Args:
+            event (pygame.event.Event): The event passed from run() method
+            *args/**kwargs
+        Raises:
+            NotImplementedError: Required implementation
+        """
+        
+        raise NotImplementedError()
+
+    @abstractmethod
+    def update(self):
+        """Required implentation of game logic. Called once per game loop.
+
+        Raises:
+            NotImplementedError: Required implementation
+        """
+        raise NotImplementedError()
+
+
+class SpriteGame(Game):
+    def __init__(
+        self,
+        screen_ref: ScreenReference,
+        player_sprites: list[GameSprite],
+        other_sprites: list[GameSprite],
+    ):
+        """Create new instance of SpriteGame object.  Invokes pygame.init().  Must
+        implement update_sprites()
+
+        Args:
+            settings (ScreenSettings): Information needed to update the screen
+            player_sprite (GameSprite): The sprite to be used for the player
+            *other_sprites (GameSprite): Any other sprites needed for the game
+        """
+        super().__init__(screen_ref=screen_ref)
+        self.player_sprites: list[GameSprite] = player_sprites
+        self.player_group = pygame.sprite.Group(player_sprites)
+        self.other_sprites_group = pygame.sprite.Group(other_sprites)

system_b-1.1.4/src/system_b/images/__init__.py

@@ -0,0 +1,5 @@
+from .images import (
+    SpriteSheet,
+    SpriteSheetList,
+    SpriteSheetMap
+)

system_b-1.1.4/src/system_b/images/images.py

@@ -0,0 +1,100 @@
+from pygame import Rect, Surface
+
+
+class SpriteSheet:
+    """Allows user to access segements of a sprite sheet"""
+
+    def __init__(self, spritesheet: Surface, bg_color: str | None = None) -> None:
+        self.spritesheet = spritesheet
+        self.rect = self.spritesheet.get_rect()
+        self.bg_color = bg_color
+
+    def get_spritesheet_segment(self, rect: Rect) -> Surface:
+        """Get a segment of the spritesheet using the given coordinates
+
+        Args:
+            rect (Rect): The coordinates of the segment you want me to find in the spritesheet
+
+        Returns:
+            Surface: The sprite from the spritesheet using the given coordinates
+        """
+        image = Surface(rect.size)
+        if self.bg_color is not None:
+            image.fill(self.bg_color)
+        image.blit(self.spritesheet, (0, 0), rect)
+        return image
+
+
+class SpriteSheetDataStruct(SpriteSheet):
+    """Base Sprite Sheet structure for sprite sheet data structures"""
+
+    def __init__(
+        self,
+        spritesheet: Surface,
+        n_sprites: int = 1,
+        n_lists: int = 1,
+        bg_color: str | None = None,
+    ) -> None:
+        super().__init__(spritesheet, bg_color)
+        self.n_lists = n_lists
+        self.n_sprites = n_sprites
+        self.sprite_size = Rect((0, 0), (self.rect.height, self.rect.width / n_sprites))
+        self.sprite_rects = self._get_sprite_rects()
+
+    def _get_sprite_rects(self) -> list[Rect]:
+        return [
+            # add a new rectangle for n sprites in this sheet (by m lists)
+            Rect(
+                (self.sprite_size.x + i * self.sprite_size.w, self.sprite_size.y),
+                self.sprite_size.size,
+            )
+            for i in range(self.n_sprites)
+            for _ in range(self.n_lists)
+        ]
+
+
+class SpriteSheetList(SpriteSheetDataStruct):
+    """implements sprite sheet as a list of sprites.  sprites are indexed"""
+
+    def __getitem__(self, index: int) -> Surface:
+        if index >= len(self.sprite_rects):
+            msg = f"index {index} out of bounds"
+            raise IndexError(msg)
+
+        return self.get_spritesheet_segment(self.sprite_rects[index])
+
+
+class SpriteSheetMap(SpriteSheetDataStruct):
+    """Implements a sprite sheet as a dictionary of sprites"""
+
+    def __init__(
+        self,
+        spritesheet: Surface,
+        keys: list[str] = ["0"],
+        n_sprites: int = 1,
+        n_lists: int = 1,
+        bg_color: str | None = None,
+    ) -> None:
+        super().__init__(spritesheet, n_sprites, n_lists, bg_color)
+        if len(keys) < len(self.sprite_rects):
+            raise Exception("Not enough keys for sprites determined")
+
+        self.keys = keys
+        self.sprite_map = {
+            self.keys[i]: self.sprite_rects[i] for i in range(len(self.keys))
+        }
+
+    def get(self, name) -> Surface | None:
+        s = self.sprite_map.get(name)
+
+        if s is not None:
+            return self.get_spritesheet_segment(s)
+
+    def __getitem__(self, name: str) -> Surface | None:
+        s = self.sprite_map.get(name)
+
+        if s is None:
+            msg = f"No key {name}"
+            raise KeyError(msg)
+
+        return self.get_spritesheet_segment(s)

system_b-1.1.4/src/system_b/math/vector_utils.py

@@ -0,0 +1,23 @@
+from collections.abc import Callable
+
+from numpy.random import choice, rand
+from pygame import Vector2
+
+
+def get_random_vector(scalar_mag: float = 1.0, non_negative: bool = False) -> Vector2:
+    def rand_sign() -> int:
+        return choice([-1, 1]) if not non_negative else 1
+
+    return Vector2(
+        x=rand() * rand_sign() * scalar_mag,
+        y=rand() * rand_sign() * scalar_mag,
+    )
+
+
+def apply_vector_actions(
+    vector: Vector2, *actions: Callable[[Vector2], Vector2]
+) -> Vector2:
+    for action in actions:
+        vector = action(vector)
+
+    return vector

system_b-1.1.4/src/system_b/physics/__init__.py

@@ -0,0 +1 @@
+from .physics import PhysicsBody

system_b-1.1.4/src/system_b/physics/physics.py

@@ -0,0 +1,113 @@
+from numpy.random import normal
+from pygame import Vector2, Vector3
+
+
+class PhysicsBody:
+    """Applies physics to a GameSprite"""
+
+    ZERO_VECTOR = Vector2(0, 0)
+    GRAVITY = 9.8
+
+    def __init__(
+        self,
+        mass: float = 1.0,
+        position: Vector2 = ZERO_VECTOR.copy(),
+        velocity: Vector2 = ZERO_VECTOR.copy(),
+        friction: float = 0.0,
+        elasticity: float = 0.0,
+        slip: float = 1.0,
+    ):
+        """Creates new instance of PhysicsBody object
+
+        Args:
+            mass (float, optional): The mass of the body. Defaults to 1.0.
+            position (Vector2, optional): The current positional vector of the body. Defaults to (0,0).
+            friction (float, optional): Static friction force. Defaults to 0.0.
+            elasticity (float, optional): Elasticity is used in caluclating loss of energy. 0 elasticity will have no effect. Defaults to 0.0.
+            slip (float, optional): Used in calculating change in static to kinetic friction. Defaults to 1.0.
+        """
+        self.mass = mass
+        self.velociy = velocity.copy()
+        self.position = position.copy()
+        self.static_friction = friction
+        self.kinetic_friction = 0
+        self.elasticity = 1 - elasticity
+        if self.static_friction > 0:
+            self.kinetic_friction = self.static_friction * normal(loc=slip)
+
+    def force(self, acceleration: Vector2, dtime: float) -> Vector2:
+        """Applies an acceleration vector to this body's current velocity with the given change in time.
+        If friction was given, friction is calculated into the new velocity
+
+        Args:
+            acceleration (Vector2): The acceleration to apply
+            dtime (float): The change in time
+
+        Returns:
+            Vector2: The new velocity at this moment in time
+        """
+        new_velocity = acceleration * dtime
+        force = acceleration * self.mass
+
+        if force.magnitude() > self.friction_force().magnitude():
+            self.velociy += new_velocity
+        else:
+            self.velociy -= self.velociy * self.friction_force().magnitude() * dtime
+        self.move(dtime)
+
+        return self.velociy.copy()
+
+    def move(self, dtime: float) -> Vector2:
+        """Returns the position at this moment in time.\n
+        Applies velocity over dtime"""
+        self.position += self.velociy * dtime
+
+        return self.position.copy()
+
+    def on_collide(self, other):
+        """New velocity is given by V`= (V(m-s) + U2s)/(m+s)
+        for initial magnitudes Vm(self) and Us(other).  Calculates loss of
+        energy from this body's elasticity
+
+        Args:
+            other (object): The object with which this body has collided
+        """
+        assert isinstance(other, PhysicsBody)
+
+        self.velociy *= self.mass - other.mass
+        self.velociy += other.velociy * 2 * other.mass
+        self.velociy /= self.mass + other.mass
+
+        # energy loss, if any
+        self.velociy *= self.elasticity
+
+    def momentum(self) -> Vector2:
+        """This body's current momentum
+
+        Returns:
+            Vector2: Vm of this body
+        """
+        return self.velociy * self.mass
+
+    def normal_force(self) -> Vector3:
+        """The normal force of this body
+
+        Returns:
+            Vector3: (0, 0, mg)
+        """
+        return Vector3(0, 0, self.mass * self.GRAVITY)
+
+    def friction_force(self) -> Vector3:
+        """fs * N if not in motion, else fk * N
+
+        Returns:
+            Vector3: (0, 0, fN)
+        """
+        return (
+            self.static_friction * self.normal_force()
+            if self.velociy == self.ZERO_VECTOR
+            else self.kinetic_friction * self.normal_force()
+        )
+
+    def __str__(self) -> str:
+        return str(self.position)

system_b-1.1.4/src/system_b/screen/__init__.py

@@ -0,0 +1 @@
+from .screen import ScreenReference

system_b-1.1.4/src/system_b/screen/screen.py

@@ -0,0 +1,46 @@
+from abc import abstractmethod
+
+import pygame.display as display
+from pygame import FULLSCREEN, Color, Surface
+from pygame.time import Clock
+
+ColorType = str | tuple[int, int, int] | Color
+
+
+class ScreenReference:
+    """defines information needed to udpate the screen"""
+
+    def __init__(
+        self,
+        width: float = 0.0,
+        height: float = 0.0,
+        frames_per_second: int = 60,
+        bg_color: ColorType | None = None,
+        bg_image: Surface | None = None,
+    ):
+        self.clock = Clock()
+        self.bg_image = bg_image
+        self.bg_color = bg_color
+        self.frames_per_second = frames_per_second
+        self.width = width
+        self.height = height
+        if self.width == 0.0 and self.height == 0.0:
+            self.screen = display.set_mode((0, 0), FULLSCREEN)
+            self.width = self.screen.get_width()
+            self.height = self.screen.get_height()
+        else:
+            self.screen = display.set_mode((self.width, self.height))
+
+    def resize_screen(self, width: float, height: float):
+        """resizes to fullscreen by default"""
+        self.width = width
+        self.height = height
+        self.screen = display.set_mode((self.width, self.height))
+
+    def get_delta_time(self, units: int = 1000) -> float:
+        return self.clock.tick(self.frames_per_second) / units
+
+    @abstractmethod
+    def update_screen(self):
+        """Define logic for screen activity.  Required"""
+        raise NotImplementedError()

system_b-1.1.4/src/system_b/sprites/__init__.py

@@ -0,0 +1,4 @@
+from .sprites import (
+    GameSprite,
+    PhysicsSprite,
+)

system_b-1.1.4/src/system_b/sprites/sprites.py

@@ -0,0 +1,110 @@
+from abc import abstractmethod
+from collections.abc import Callable
+from typing import Any
+
+from pygame import Rect, Surface, Vector2
+from pygame.sprite import Sprite
+
+from system_b.physics import PhysicsBody
+
+
+class GameSprite(Sprite):
+    def __init__(
+        self,
+        image: Surface,
+        position: Vector2,
+        boundaries: Rect | None = None,
+        id: int = 0,
+    ):
+        """Implement a Game Sprite object. Subclass must implement GameSprite.update
+
+        Args:
+            image (Surface): The image for the sprite
+            position (Vector2): Where to put the sprite
+            boundaries (Rect | None, optional): Optional boundary vectors for this sprite (xmax, xmin, ymax, ymin). Defaults to None.
+        """
+        super().__init__()
+        self.image = image
+        _, _, *dimensions = image.get_rect()
+        self.rect = Rect(position.x, position.y, *dimensions)
+        self.position = position
+        self.boundaries = boundaries
+        self.id = id
+
+    @abstractmethod
+    def update(self, *args: Any, **kwargs: Any):
+        """Required.  Define logic to perform on this sprite once for every game loop
+
+        Args:
+            *args, **kwargs
+        """
+        raise NotImplementedError()
+
+    def _update_pos(
+        self,
+        position: Vector2 | None = None,
+        xbounds: Callable[[], None] | None = None,
+        ybounds: Callable[[], None] | None = None,
+    ):
+        """Updates position of this sprite. Maintains any given boundaries. Invokes callbacks given when boundaries are reached
+
+        Args:
+            position (Vector2 | None, optional): The new position of this sprite. Defaults to None.
+            xbounds (Callable[[], None] | None, optional): X boundary callable. Invoked when boundaries are reached, if given. Defaults to None.
+            ybounds (Callable[[], None] | None, optional): Y boundary callable. Invoked when boundaries are reached, if given. Defaults to None.
+        """
+        if position is not None:
+            self.position = position
+
+        x, y, w, h = self.rect
+
+        if self.boundaries is not None:
+            bx_max, bx_min, by_max, by_min = self.boundaries
+
+            if self.position.y > by_max - h / 2:
+                if ybounds is not None:
+                    ybounds()
+
+                self.position.y = by_max - h / 2
+
+            elif self.position.y < by_min + h / 2:
+                if ybounds is not None:
+                    ybounds()
+
+                self.position.y = by_min + h / 2
+
+            if self.position.x > bx_max - w / 2:
+                if xbounds is not None:
+                    xbounds()
+
+                self.position.x = bx_max - w / 2
+
+            elif self.position.x < bx_min + w / 2:
+                if xbounds is not None:
+                    xbounds()
+
+                self.position.x = bx_min + w / 2
+
+        x = self.position.x - w / 2
+        y = self.position.y - h / 2
+
+        self.rect = Rect(x, y, w, h)
+
+    def __str__(self) -> str:
+        return str(tuple(self.rect))
+
+
+class PhysicsSprite(GameSprite):
+    """GameSprite that uses a PhysicsBody reference to apply physics"""
+
+    def __init__(
+        self,
+        image: Surface,
+        position: Vector2,
+        physics_body: PhysicsBody,
+        boundaries: Rect | None = None,
+        id: int = 0,
+    ):
+        super().__init__(image, position, boundaries, id)
+        self.physics_body = physics_body
+        self.physics_body.position = self.position

system_b-1.1.4/src/system_b/toolkit/__init__.py

@@ -0,0 +1 @@
+from .toolkit import *

system_b-1.1.4/src/system_b/toolkit/__main__.py

@@ -0,0 +1,6 @@
+from .toolkit import main
+
+import sys
+
+if __name__ == "__main__":
+    main(sys.argv)

system_b-1.1.4/src/system_b/toolkit/toolkit.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+
+import shutil
+import os
+
+from system_b.demo import demo
+
+def main(args):
+    if len(args) == 1:
+        print("Thank you for using game-utils!")
+        print("     --demo to play the demo game")
+        print("     --copy to copy the demo game file into a new project")
+    elif "--demo" in args:
+        print("Running demo...")
+        demo.main()
+        print("Game over...")
+    elif "--copy" in args:
+        shutil.copy(os.path.relpath(demo.__file__), os.path.curdir)
+

system_b-1.1.4/src/system_b.egg-info/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: system-b
+Version: 1.1.4
+Summary: A pygame engine for common game operations like vector math and maintaining events in the game loop
+Author-email: Bee Hall <bhall1224@gmail.com>
+Project-URL: Homepage, https://gitlab.com/bhall/game-utils
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: <=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pygame
+Requires-Dist: numpy
+Dynamic: license-file
+
+# Game Utils
+
+>1.1.4
+
+## `game-utils` is a pygame engine.  The engine includes modules to facilitate boilerplate game operations. 
+
+### Requirements
+
+**Dependences:**
+- pygame
+- numpy
+
+**Demo Game**
+
+Run: `python -m game_utils.demo` or `python -m game_utils.toolkit --demo` to play the demo bouncy ball game!
+
+Run: `python -m game_utils.toolkit --copy` to copy the sample project to your directory!
+
+---
+
+## See Also...
+
+<p><b>My ongoing game projects!</b></p>
+
+- [GitLab](https://gitlab.com/bhall)

system_b-1.1.4/src/system_b.egg-info/SOURCES.txt

@@ -0,0 +1,34 @@
+LICENSE
+README.md
+pyproject.toml
+src/system_b/__init__.py
+src/system_b.egg-info/PKG-INFO
+src/system_b.egg-info/SOURCES.txt
+src/system_b.egg-info/dependency_links.txt
+src/system_b.egg-info/requires.txt
+src/system_b.egg-info/top_level.txt
+src/system_b/controller/__init__.py
+src/system_b/controller/controller.py
+src/system_b/demo/__init__.py
+src/system_b/demo/__main__.py
+src/system_b/demo/demo.py
+src/system_b/exceptions/__init__.py
+src/system_b/exceptions/game_exception.py
+src/system_b/game/__init__.py
+src/system_b/game/game.py
+src/system_b/images/__init__.py
+src/system_b/images/images.py
+src/system_b/math/__init__.py
+src/system_b/math/vector_utils.py
+src/system_b/physics/__init__.py
+src/system_b/physics/physics.py
+src/system_b/screen/__init__.py
+src/system_b/screen/screen.py
+src/system_b/sprites/__init__.py
+src/system_b/sprites/sprites.py
+src/system_b/toolkit/__init__.py
+src/system_b/toolkit/__main__.py
+src/system_b/toolkit/toolkit.py
+tests/test_game.py
+tests/test_images.py
+tests/test_physics.py

system_b-1.1.4/src/system_b.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

system_b-1.1.4/src/system_b.egg-info/requires.txt

@@ -0,0 +1,2 @@
+pygame
+numpy

system_b-1.1.4/src/system_b.egg-info/top_level.txt

@@ -0,0 +1 @@
+system_b

system_b-1.1.4/tests/test_game.py

@@ -0,0 +1,37 @@
+import logging
+
+import pygame.event
+from pygame.locals import K_ESCAPE, QUIT, USEREVENT
+
+from system_b.game import Game
+from system_b.screen import ScreenReference
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.WARNING)
+
+TESTEVENT = USEREVENT
+
+
+class MockGame(Game):
+    def __init__(self):
+        super().__init__()
+        self.state = 0
+        self.event = False
+
+    def update(self):
+        self.state += 1
+        if self.state == 1:
+            pygame.event.post(pygame.event.Event(TESTEVENT))
+        if self.state == 3:
+            self._running = False
+
+    def events(self, event, *args, **kwargs):
+        if event.type == TESTEVENT:
+            self.event = True
+
+
+def test_run():
+    tg = MockGame()
+    tg.run()
+    assert tg.state == 3
+    assert tg.event == True

system_b-1.1.4/tests/test_images.py

@@ -0,0 +1,35 @@
+from pygame import Rect, Surface
+
+from system_b.images import *
+
+SPRITESHEET_SIM_RECT = Rect(0, 0, 100, 100)
+SPRITESHEET_SIM__SURFACT = Surface(SPRITESHEET_SIM_RECT.size)
+
+
+def test_sprite_sheet():
+    ssheet = SpriteSheet(spritesheet=SPRITESHEET_SIM__SURFACT)
+
+    seg = ssheet.get_spritesheet_segment(Rect(0, 0, 20, 20))
+    assert seg.get_rect().size == (20, 20)
+
+
+def test_sprite_sheet_list():
+    ssheet_list = SpriteSheetList(
+        spritesheet=SPRITESHEET_SIM__SURFACT,
+        n_sprites=5,
+    )
+
+    seg = ssheet_list[0]
+    assert seg.get_rect().size == (100, 20)
+
+
+def test_sprite_sheet_map():
+    ssheet_map = SpriteSheetMap(
+        spritesheet=SPRITESHEET_SIM__SURFACT,
+        keys=["a", "b", "c", "d", "e"],
+        n_sprites=5,
+    )
+
+    seg = ssheet_map["a"]
+    assert seg is not None
+    assert seg.get_rect().size == (100, 20)

system_b-1.1.4/tests/test_physics.py

@@ -0,0 +1,77 @@
+import math
+
+from pygame import Vector2
+
+from system_b.physics import *
+
+
+def test_physics_body():
+    pb = PhysicsBody()
+
+    assert pb is not None
+    assert pb.elasticity == 1.0
+    assert pb.mass == 1.0
+    assert pb.static_friction == 0.0
+    assert pb.kinetic_friction == 0.0
+
+    pb2 = PhysicsBody(
+        mass=2.0,
+        friction=0.009,
+        elasticity=0.02,
+        slip=1.1,
+    )
+
+    assert pb2 is not None
+    assert math.fabs(pb2.kinetic_friction) > 0
+
+
+def test_forces():
+    pb = PhysicsBody(mass=2.0)
+
+    v = pb.force(Vector2(0.1, -0.1), 0.1)
+    assert v is not None
+    assert v == Vector2(0.01, -0.01)
+
+    v2 = pb.move(0.08)
+
+    assert v2 is not None
+    assert (v2 - v).magnitude() != 0
+
+
+def test_collisions():
+    v_i1 = Vector2(-1, 0)
+    d_i1 = Vector2(1, 0)
+
+    pb = PhysicsBody(
+        mass=2.0,
+        position=d_i1,
+        velocity=v_i1,
+    )
+
+    v_i2 = Vector2(1, 0)
+    d_i2 = Vector2(-1, 0)
+
+    pb2 = PhysicsBody(
+        mass=3.0,
+        position=d_i2,
+        velocity=v_i2,
+    )
+
+    t1 = 0.1
+
+    d1_t1 = pb.move(t1)
+    d2_t1 = pb2.move(t1)
+
+    assert d1_t1 is not d_i1
+    assert d2_t1 is not d_i2
+
+    pb.on_collide(pb2)
+    pb2.on_collide(pb)
+
+    t2 = 0.2
+
+    d1_t2 = pb.move(t2)
+    d2_t2 = pb2.move(t2)
+
+    assert d1_t2 is not d1_t1
+    assert d2_t2 is not d2_t1