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.

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.

Requirements

• Python >=3.11
• pygame(-ce) >=2.6.1

Installation

pip install playpy

If that does not work:

python -m pip install playpy

---

Core Concepts

Workspace

Workspace owns:

• the window
• render loop
• input state
• scene stack
• coroutine scheduler

Key methods:

ws.run()
ws.quit()
ws.wait(seconds)

ws.queue_scene_change(scene)
ws.queue_scene_push(scene)
ws.queue_scene_pop(scene=None)

ws.step()

Scene Scope

Temporarily push a scene using a context manager:

with ws.scene_scope(scene) as (scn, handle):
    ...

Call:

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:

Relative scale values.

plp.FRect(x, y, w, h)

Rect:

Absolute pixel offsets.

plp.Rect(x, y, w, h)

---

Final element rectangle:

(scale * parent_size) + offset

Helpers:

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

Sprites load and store images. Initialize them by passing in a path. (Path or str object)

Animations store multiple Sprites and allow for changing of animation settings (FPS, loop, etc.) Pass in either sprite paths (Path or str object), or Sprites themselves.

Sounds

Sounds load and store user-imported sounds from sound files. Initialize them by passing in a path. (Path or str object)

Useful methods:

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.

child.parent = parent

or:

parent.add_child(child)

Relationship helpers:

is_parent_of()
is_child_of()

is_ancestor_of()
is_descendant_of()

Properties:

parent
children
ancestors
descendants

---

Rendering System

PlayPy now uses a compositing pipeline.

Element.draw() returns a SurfaceHandler instead of drawing directly to the workspace.

This enables:

• outlines for arbitrary shapes
• gradients inheriting shape alpha
• subtree compositing
• layered visual effects
• future post-processing support

---

Elements

Core Elements

• Panel
• Text
• Button
• Textbox
• Line
• Scene

Effects

Effect is a subclass of Element that visually modifies its parent subtree.

Built-in effects:

• Gradient
• ButtonGradient
• Outline
• BorderRadius
• VisualLayer

Effects are ordered using z.

Typical layering:

Negative z:
    backgrounds/gradients

Normal z:
    content

Positive z:
    outlines/glows/overlays

Components

Components modify behavior/layout but do not draw.

Built-in components:

• Padding
• Font
• Camera
• Scrollable
• GlobalElement

Attach/get/remove:

element.set_component(component)

element.get_component(ComponentType)

element.remove_component(ComponentType)

or:

component.parent = element

---

Input State

Access input using:

workspace.input

Controller profile changes are tracked on the workspace for the current frame:

workspace.profile_changes
workspace.profiles_added
workspace.profiles_removed

Properties:

keys_pressed
key_downs
key_ups

mouse_buttons_pressed
mouse_downs
mouse_ups

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
runtime
quit

Helper methods:

key_held()
key_down()
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 InputActions for easier keybind compatibility. Any matching key, mouse button, or controller button can trigger the action.

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]
)

---

Hover State

Workspace hover helpers:

is_mouse_top(element)
is_mouse_over(element)

just_hovered(element)
just_unhovered(element)

just_hovered_inclusive(element)
just_unhovered_inclusive(element)

Event helpers:

@on_hover(...)
@on_unhover(...)
@while_hovered(...)

@on_hover_inclusive(...)
@on_unhover_inclusive(...)
@while_hovered_inclusive(...)

---

Events

Decorator helpers create Event elements.

@plp.on_start(target)
@plp.on_update(target)
@plp.on_quit(target)

@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)

Events attached to the main workspace are global by default.

Example:

@plp.on_update(ws)
def tick(w: plp.Workspace):
    if w.input.key_down(plp.Key.ESCAPE):
        w.quit()

---

Coroutines

Event-like functions can yield.

If a handler returns a generator, PlayPy resumes it on future frames.

Example:

def flash(_: plp.Workspace):
    for _ in range(60):
        print("frame")
        yield

Supported in:

• event callbacks
• button callbacks
• textbox callbacks
• other event-like handlers

---

Textbox Features

Textbox supports:

• placeholders
• caret blinking
• text confirmation/reverting
• character filtering
• maximum length
• coroutine callbacks

Useful arguments:

is_char_accepted=
on_text_updated=
confirm_on_click_off=

Special keys:

Backspace -> remove character
Delete    -> clear text
Return    -> confirm text
Escape    -> revert text

---

Scenes

Scenes support lifecycle hooks:

on_enter()
on_exit()
on_pause()
on_resume()

Scene changes are queued internally.

---

Cameras and Scrolling

Camera offsets descendant elements.

Scrollable extends camera functionality with built-in scrolling support.

Example:

scrollable = plp.Scrollable()
scrollable.parent = panel

---

VisualLayer

VisualLayers render Sprites, Animations, colors, and shader-like effects.

VisualLayer constructor:

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.

plp.log(severity, category, message)

Severities:

plp.Severity.INFO
plp.Severity.WARNING
plp.Severity.ERROR
plp.Severity.CRITICAL

ERROR and CRITICAL are treated as NoReturn.