PlayPy 0.3.0__tar.gz → 0.4.0__tar.gz

{playpy-0.3.0 → playpy-0.4.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: PlayPy
-Version: 0.3.0
-Summary: PlayPy is a lightweight Python library for creating simple games and interactive applications with ease. It provides a straightforward API for handling graphics, input, and basic game mechanics, making it ideal for beginners and those looking to quickly prototype their ideas.
+Version: 0.4.0
+Summary: PlayPy is a lightweight Python library for creating games, tools, and interactive applications using a retained-mode UI and scene system built on top of pygame. It focuses on rapid prototyping, composable rendering, and simple but powerful layout primitives.
 Author-email: angel <angyv2861@gmail.com>
 Requires-Python: >=3.14
 Description-Content-Type: text/markdown
@@ -10,7 +10,7 @@ Requires-Dist: pygame-ce>=2.5.6
 Requires-Dist: colorama>=0.4.6
 Dynamic: license-file
 
-# PlayPy (0.3.0)
+# PlayPy (0.4.0)
 
 PlayPy is a lightweight Python library for creating games, tools, and interactive applications using a retained-mode UI and scene system built on top of pygame. It focuses on rapid prototyping, composable rendering, and simple but powerful layout primitives.
 
@@ -49,6 +49,7 @@ Key methods:
 ```python
 ws.run()
 ws.quit()
+ws.wait(seconds)
 
 ws.queue_scene_change(scene)
 ws.queue_scene_push(scene)
@@ -74,26 +75,30 @@ handle.disconnect()
 
 to remotely pop the scoped scene.
 
+The scoped scene will automatically be disconnected if not disconnected manually.
+
 ---
 
 ## Layout Values
 
 PlayPy uses two rectangle value types:
 
-### `FRect`
+### `FRect`:
 Relative scale values.
 
 ```python
 plp.FRect(x, y, w, h)
 ```
 
-### `Rect`
+### `Rect`:
 Absolute pixel offsets.
 
 ```python
 plp.Rect(x, y, w, h)
 ```
 
+---
+
 Final element rectangle:
 
 ```text
@@ -103,15 +108,45 @@ Final element rectangle:
 Helpers:
 
 ```python
-plp.empty_rect()
-plp.empty_frect()
-plp.full_screen_rect()
+plp.empty_rect() -> Rect(0, 0, 0, 0)
+plp.empty_frect() -> FRect(0, 0, 0, 0)
+plp.full_screen_rect() -> (FRect(0, 0, 1, 1), Rect(0, 0, 0, 0))
 ```
 
 Rect types are iterable and support multiple constructor overloads.
 
 ---
 
+## Assets
+
+Assets are reusable wrappers around external files such as images, animations, and sounds.
+
+PlayPy assets load lazily: they store the path when created, then load the underlying pygame resource when needed. You can also call `load()` ahead of time to preload an asset and reduce latency during gameplay.
+
+### Sprites and Animations
+
+`Sprite`s load and store images. Initialize them by passing in a path. (`Path` or `str` object)
+
+`Animation`s store multiple `Sprite`s and allow for changing of animation settings (FPS, loop, etc.)
+Pass in either sprite paths (`Path` or `str` object), or `Sprite`s themselves.
+
+### Sounds
+
+`Sound`s load and store user-imported sounds from sound files. Initialize them by passing in a path. (`Path` or `str` object)
+
+Useful methods:
+```python
+sound = plp.Sound("my_awesome_sound.wav")
+
+sound.load()
+sound.play(loop_amt=3, maxtime=10, fade_ms=500)
+sound.stop()
+sound.set_volume(.5)
+volume = sound.get_volume()
+```
+
+---
+
 # Parenting
 
 Any `Element` can contain children.
@@ -183,6 +218,7 @@ Built-in effects:
 - `ButtonGradient`
 - `Outline`
 - `BorderRadius`
+- `VisualLayer`
 
 Effects are ordered using `z`.
 
@@ -237,6 +273,14 @@ Access input using:
 workspace.input
 ```
 
+Controller profile changes are tracked on the workspace for the current frame:
+
+```python
+workspace.profile_changes
+workspace.profiles_added
+workspace.profiles_removed
+```
+
 Properties:
 
 ```python
@@ -252,6 +296,15 @@ mouse_pos
 mouse_delta
 mouse_wheel
 
+controller_buttons_pressed
+controller_ups
+controller_downs
+
+controller_left_sticks
+controller_right_sticks
+controller_left_sticks_deltas
+controller_right_stick_deltas
+
 text_input
 
 dt
@@ -269,6 +322,30 @@ key_up()
 mousebutton_held()
 mousebutton_down()
 mousebutton_up()
+
+controllerbutton_held()
+controllerbutton_down()
+controllerbutton_up()
+
+left_stick(profile)
+right_stick(profile)
+left_stick_delta(profile)
+right_stick_delta(profile)
+
+input_action_held()
+input_action_down()
+input_action_up()
+```
+
+Use `InputAction`s for easier keybind compatibility. Any matching key, mouse button, or controller button can trigger the action.
+
+```python
+keybind = plp.InputAction(
+    keys = [plp.Key.SPACE, plp.Key.RETURN],
+    mouse_buttons = [plp.MouseButton.LEFT],
+    controller_buttons = [plp.ControllerButton.A, plp.ControllerButton.B],
+    profiles = [plp.InputProfile.KEYBOARD_MOUSE, plp.InputProfile.CONTROLLER_0]
+)
 ```
 
 ---
@@ -313,6 +390,10 @@ Decorator helpers create `Event` elements.
 
 @plp.on_scene_change(target)
 
+@plp.on_profile_changed(target)
+@plp.on_profile_added(target)
+@plp.on_profile_removed(target)
+
 @plp.create_event(target, condition)
 ```
 
@@ -383,7 +464,7 @@ Escape    -> revert text
 
 # Scenes
 
-Scenes support lifecycle hooks:
+`Scene`s support lifecycle hooks:
 
 ```python
 on_enter()
@@ -411,6 +492,24 @@ scrollable.parent = panel
 
 ---
 
+### VisualLayer
+
+`VisualLayer`s render `Sprite`s, `Animation`s, colors, and shader-like effects.
+
+`VisualLayer` constructor:
+```python
+VisualLayer(
+    visual: plp.Sprite | plp.Animation | plp.ColorValue,
+    blend_mode: plp.BlendMode = plp.BlendMode.RGB_SUBTRACT,
+    scale: plp.FRectValue = (0, 0, 1, 1),
+    offset: plp.RectValue = (0, 0, 0, 0),
+    z: int = -1_000_000,
+    visible: bool = True,
+)
+```
+
+---
+
 # Logging
 
 PlayPy replaces standard exceptions/logging with a categorized logging system.

playpy-0.3.0/src/PlayPy.egg-info/PKG-INFO → playpy-0.4.0/README.md

@@ -1,16 +1,4 @@
-Metadata-Version: 2.4
-Name: PlayPy
-Version: 0.3.0
-Summary: PlayPy is a lightweight Python library for creating simple games and interactive applications with ease. It provides a straightforward API for handling graphics, input, and basic game mechanics, making it ideal for beginners and those looking to quickly prototype their ideas.
-Author-email: angel <angyv2861@gmail.com>
-Requires-Python: >=3.14
-Description-Content-Type: text/markdown
-License-File: LICENSE.txt
-Requires-Dist: pygame-ce>=2.5.6
-Requires-Dist: colorama>=0.4.6
-Dynamic: license-file
-
-# PlayPy (0.3.0)
+# PlayPy (0.4.0)
 
 PlayPy is a lightweight Python library for creating games, tools, and interactive applications using a retained-mode UI and scene system built on top of pygame. It focuses on rapid prototyping, composable rendering, and simple but powerful layout primitives.
 
@@ -49,6 +37,7 @@ Key methods:
 ```python
 ws.run()
 ws.quit()
+ws.wait(seconds)
 
 ws.queue_scene_change(scene)
 ws.queue_scene_push(scene)
@@ -74,26 +63,30 @@ handle.disconnect()
 
 to remotely pop the scoped scene.
 
+The scoped scene will automatically be disconnected if not disconnected manually.
+
 ---
 
 ## Layout Values
 
 PlayPy uses two rectangle value types:
 
-### `FRect`
+### `FRect`:
 Relative scale values.
 
 ```python
 plp.FRect(x, y, w, h)
 ```
 
-### `Rect`
+### `Rect`:
 Absolute pixel offsets.
 
 ```python
 plp.Rect(x, y, w, h)
 ```
 
+---
+
 Final element rectangle:
 
 ```text
@@ -103,15 +96,45 @@ Final element rectangle:
 Helpers:
 
 ```python
-plp.empty_rect()
-plp.empty_frect()
-plp.full_screen_rect()
+plp.empty_rect() -> Rect(0, 0, 0, 0)
+plp.empty_frect() -> FRect(0, 0, 0, 0)
+plp.full_screen_rect() -> (FRect(0, 0, 1, 1), Rect(0, 0, 0, 0))
 ```
 
 Rect types are iterable and support multiple constructor overloads.
 
 ---
 
+## Assets
+
+Assets are reusable wrappers around external files such as images, animations, and sounds.
+
+PlayPy assets load lazily: they store the path when created, then load the underlying pygame resource when needed. You can also call `load()` ahead of time to preload an asset and reduce latency during gameplay.
+
+### Sprites and Animations
+
+`Sprite`s load and store images. Initialize them by passing in a path. (`Path` or `str` object)
+
+`Animation`s store multiple `Sprite`s and allow for changing of animation settings (FPS, loop, etc.)
+Pass in either sprite paths (`Path` or `str` object), or `Sprite`s themselves.
+
+### Sounds
+
+`Sound`s load and store user-imported sounds from sound files. Initialize them by passing in a path. (`Path` or `str` object)
+
+Useful methods:
+```python
+sound = plp.Sound("my_awesome_sound.wav")
+
+sound.load()
+sound.play(loop_amt=3, maxtime=10, fade_ms=500)
+sound.stop()
+sound.set_volume(.5)
+volume = sound.get_volume()
+```
+
+---
+
 # Parenting
 
 Any `Element` can contain children.
@@ -183,6 +206,7 @@ Built-in effects:
 - `ButtonGradient`
 - `Outline`
 - `BorderRadius`
+- `VisualLayer`
 
 Effects are ordered using `z`.
 
@@ -237,6 +261,14 @@ Access input using:
 workspace.input
 ```
 
+Controller profile changes are tracked on the workspace for the current frame:
+
+```python
+workspace.profile_changes
+workspace.profiles_added
+workspace.profiles_removed
+```
+
 Properties:
 
 ```python
@@ -252,6 +284,15 @@ mouse_pos
 mouse_delta
 mouse_wheel
 
+controller_buttons_pressed
+controller_ups
+controller_downs
+
+controller_left_sticks
+controller_right_sticks
+controller_left_sticks_deltas
+controller_right_stick_deltas
+
 text_input
 
 dt
@@ -269,6 +310,30 @@ key_up()
 mousebutton_held()
 mousebutton_down()
 mousebutton_up()
+
+controllerbutton_held()
+controllerbutton_down()
+controllerbutton_up()
+
+left_stick(profile)
+right_stick(profile)
+left_stick_delta(profile)
+right_stick_delta(profile)
+
+input_action_held()
+input_action_down()
+input_action_up()
+```
+
+Use `InputAction`s for easier keybind compatibility. Any matching key, mouse button, or controller button can trigger the action.
+
+```python
+keybind = plp.InputAction(
+    keys = [plp.Key.SPACE, plp.Key.RETURN],
+    mouse_buttons = [plp.MouseButton.LEFT],
+    controller_buttons = [plp.ControllerButton.A, plp.ControllerButton.B],
+    profiles = [plp.InputProfile.KEYBOARD_MOUSE, plp.InputProfile.CONTROLLER_0]
+)
 ```
 
 ---
@@ -313,6 +378,10 @@ Decorator helpers create `Event` elements.
 
 @plp.on_scene_change(target)
 
+@plp.on_profile_changed(target)
+@plp.on_profile_added(target)
+@plp.on_profile_removed(target)
+
 @plp.create_event(target, condition)
 ```
 
@@ -383,7 +452,7 @@ Escape    -> revert text
 
 # Scenes
 
-Scenes support lifecycle hooks:
+`Scene`s support lifecycle hooks:
 
 ```python
 on_enter()
@@ -411,6 +480,24 @@ scrollable.parent = panel
 
 ---
 
+### VisualLayer
+
+`VisualLayer`s render `Sprite`s, `Animation`s, colors, and shader-like effects.
+
+`VisualLayer` constructor:
+```python
+VisualLayer(
+    visual: plp.Sprite | plp.Animation | plp.ColorValue,
+    blend_mode: plp.BlendMode = plp.BlendMode.RGB_SUBTRACT,
+    scale: plp.FRectValue = (0, 0, 1, 1),
+    offset: plp.RectValue = (0, 0, 0, 0),
+    z: int = -1_000_000,
+    visible: bool = True,
+)
+```
+
+---
+
 # Logging
 
 PlayPy replaces standard exceptions/logging with a categorized logging system.

{playpy-0.3.0 → playpy-0.4.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "PlayPy"
-version = "0.3.0"
-description = "PlayPy is a lightweight Python library for creating simple games and interactive applications with ease. It provides a straightforward API for handling graphics, input, and basic game mechanics, making it ideal for beginners and those looking to quickly prototype their ideas."
+version = "0.4.0"
+description = "PlayPy is a lightweight Python library for creating games, tools, and interactive applications using a retained-mode UI and scene system built on top of pygame. It focuses on rapid prototyping, composable rendering, and simple but powerful layout primitives."
 readme = "README.md"
 requires-python = ">=3.14"
 dependencies = ["pygame-ce>=2.5.6", "colorama>=0.4.6"]

playpy-0.3.0/README.md → playpy-0.4.0/src/PlayPy.egg-info/PKG-INFO

@@ -1,4 +1,16 @@
-# PlayPy (0.3.0)
+Metadata-Version: 2.4
+Name: PlayPy
+Version: 0.4.0
+Summary: PlayPy is a lightweight Python library for creating games, tools, and interactive applications using a retained-mode UI and scene system built on top of pygame. It focuses on rapid prototyping, composable rendering, and simple but powerful layout primitives.
+Author-email: angel <angyv2861@gmail.com>
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: pygame-ce>=2.5.6
+Requires-Dist: colorama>=0.4.6
+Dynamic: license-file
+
+# PlayPy (0.4.0)
 
 PlayPy is a lightweight Python library for creating games, tools, and interactive applications using a retained-mode UI and scene system built on top of pygame. It focuses on rapid prototyping, composable rendering, and simple but powerful layout primitives.
 
@@ -37,6 +49,7 @@ Key methods:
 ```python
 ws.run()
 ws.quit()
+ws.wait(seconds)
 
 ws.queue_scene_change(scene)
 ws.queue_scene_push(scene)
@@ -62,26 +75,30 @@ handle.disconnect()
 
 to remotely pop the scoped scene.
 
+The scoped scene will automatically be disconnected if not disconnected manually.
+
 ---
 
 ## Layout Values
 
 PlayPy uses two rectangle value types:
 
-### `FRect`
+### `FRect`:
 Relative scale values.
 
 ```python
 plp.FRect(x, y, w, h)
 ```
 
-### `Rect`
+### `Rect`:
 Absolute pixel offsets.
 
 ```python
 plp.Rect(x, y, w, h)
 ```
 
+---
+
 Final element rectangle:
 
 ```text
@@ -91,15 +108,45 @@ Final element rectangle:
 Helpers:
 
 ```python
-plp.empty_rect()
-plp.empty_frect()
-plp.full_screen_rect()
+plp.empty_rect() -> Rect(0, 0, 0, 0)
+plp.empty_frect() -> FRect(0, 0, 0, 0)
+plp.full_screen_rect() -> (FRect(0, 0, 1, 1), Rect(0, 0, 0, 0))
 ```
 
 Rect types are iterable and support multiple constructor overloads.
 
 ---
 
+## Assets
+
+Assets are reusable wrappers around external files such as images, animations, and sounds.
+
+PlayPy assets load lazily: they store the path when created, then load the underlying pygame resource when needed. You can also call `load()` ahead of time to preload an asset and reduce latency during gameplay.
+
+### Sprites and Animations
+
+`Sprite`s load and store images. Initialize them by passing in a path. (`Path` or `str` object)
+
+`Animation`s store multiple `Sprite`s and allow for changing of animation settings (FPS, loop, etc.)
+Pass in either sprite paths (`Path` or `str` object), or `Sprite`s themselves.
+
+### Sounds
+
+`Sound`s load and store user-imported sounds from sound files. Initialize them by passing in a path. (`Path` or `str` object)
+
+Useful methods:
+```python
+sound = plp.Sound("my_awesome_sound.wav")
+
+sound.load()
+sound.play(loop_amt=3, maxtime=10, fade_ms=500)
+sound.stop()
+sound.set_volume(.5)
+volume = sound.get_volume()
+```
+
+---
+
 # Parenting
 
 Any `Element` can contain children.
@@ -171,6 +218,7 @@ Built-in effects:
 - `ButtonGradient`
 - `Outline`
 - `BorderRadius`
+- `VisualLayer`
 
 Effects are ordered using `z`.
 
@@ -225,6 +273,14 @@ Access input using:
 workspace.input
 ```
 
+Controller profile changes are tracked on the workspace for the current frame:
+
+```python
+workspace.profile_changes
+workspace.profiles_added
+workspace.profiles_removed
+```
+
 Properties:
 
 ```python
@@ -240,6 +296,15 @@ mouse_pos
 mouse_delta
 mouse_wheel
 
+controller_buttons_pressed
+controller_ups
+controller_downs
+
+controller_left_sticks
+controller_right_sticks
+controller_left_sticks_deltas
+controller_right_stick_deltas
+
 text_input
 
 dt
@@ -257,6 +322,30 @@ key_up()
 mousebutton_held()
 mousebutton_down()
 mousebutton_up()
+
+controllerbutton_held()
+controllerbutton_down()
+controllerbutton_up()
+
+left_stick(profile)
+right_stick(profile)
+left_stick_delta(profile)
+right_stick_delta(profile)
+
+input_action_held()
+input_action_down()
+input_action_up()
+```
+
+Use `InputAction`s for easier keybind compatibility. Any matching key, mouse button, or controller button can trigger the action.
+
+```python
+keybind = plp.InputAction(
+    keys = [plp.Key.SPACE, plp.Key.RETURN],
+    mouse_buttons = [plp.MouseButton.LEFT],
+    controller_buttons = [plp.ControllerButton.A, plp.ControllerButton.B],
+    profiles = [plp.InputProfile.KEYBOARD_MOUSE, plp.InputProfile.CONTROLLER_0]
+)
 ```
 
 ---
@@ -301,6 +390,10 @@ Decorator helpers create `Event` elements.
 
 @plp.on_scene_change(target)
 
+@plp.on_profile_changed(target)
+@plp.on_profile_added(target)
+@plp.on_profile_removed(target)
+
 @plp.create_event(target, condition)
 ```
 
@@ -371,7 +464,7 @@ Escape    -> revert text
 
 # Scenes
 
-Scenes support lifecycle hooks:
+`Scene`s support lifecycle hooks:
 
 ```python
 on_enter()
@@ -399,6 +492,24 @@ scrollable.parent = panel
 
 ---
 
+### VisualLayer
+
+`VisualLayer`s render `Sprite`s, `Animation`s, colors, and shader-like effects.
+
+`VisualLayer` constructor:
+```python
+VisualLayer(
+    visual: plp.Sprite | plp.Animation | plp.ColorValue,
+    blend_mode: plp.BlendMode = plp.BlendMode.RGB_SUBTRACT,
+    scale: plp.FRectValue = (0, 0, 1, 1),
+    offset: plp.RectValue = (0, 0, 0, 0),
+    z: int = -1_000_000,
+    visible: bool = True,
+)
+```
+
+---
+
 # Logging
 
 PlayPy replaces standard exceptions/logging with a categorized logging system.