PlayPy 0.2.1

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.

PlayPy (0.2.1)

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.

Requirements

• Python >=3.11
• pygame >=2.6.1

Installation

To install PlayPy, enter the following line into your terminal: pip install playpy, or python -m pip install playpy if the first line does not work.

Core Concepts

Workspace

Workspace owns the window, render loop, input state, scene stack, and modal stack.

Key methods:

• run() starts runtime loop
• quit() stops runtime loop
• queue_scene_change(scene) replaces the current scene
• queue_scene_push(scene) / queue_scene_pop() stacks scenes
• queue_modal_push(element) / queue_modal_pop() manages overlays

Layout Values

PlayPy uses two rectangle value types:

• FRect(*args) Relative scale (fraction of parent rectangle).
• Rect(*args) Absolute pixel offsets applied on top of scale.
• Overloads are: x, y, w, h \ topleft, size \ (x, y, w, h) \ (topleft, size)

Final element rect = scale * parent_size + offset.

Parenting

Any UIElement can contain children. Assigning parent wires it automatically:

child.parent = parent

Or use helpers:

parent.add_child(child)

You can use the parent, ancestors, children, and descendants properties to find ancestors or descendants of an element.

You can use other built-in methods to tell descendance:

• is_parent_of(child), is_child_of(parent)
• is_ancestor_of(descendant), is_descendant_of(ancestor)

Built-in Elements

• UIPanel: colored rectangle container
• UIScrollablePanel: panel with wheel scrolling
• UIText: wrapped text rendering with alignment
• UIButton: clickable button with hover/pressed colors
• UITextbox: single-line text input with placeholder/caret
• Scene: root container for scene lifecycle

Modifiers

Modifiers attach style/behavior to a single element.

• UIPadding(scale=0, offset=10) - Adds padding to the element.
• UIOutline(color, width, edge_type) - Adds an outline to the element.
• UIBorderRadius(radius) - Adds a border radius (rounded corners) to the element.
• UIGradient(start_color, end_color, direction) - Converts the background color of the element to a gradient.
• UIFont(font_path=None, font_size=None, bold=None, italic=None, antialias=None) - Changes the font of the text.
• GlobalElement() - If added to a Workspace descended element, makes this object shown and handled even when another scene is running.

Attach/get/remove:

element.set_modifier(plp.UIOutline((0, 0, 0), 2, "middle"))
outline = element.get_modifier(plp.UIOutline)
element.remove_modifier(plp.UIOutline)

Event Helpers

Decorator helpers create Event elements attached to a workspace, scene, or element.

• @on_start(target) - Runs when the scene/workspace starts running/
• @on_update(target)
• @on_quit(target)
• @on_scene_change(target)
• @on_modal_change(target)
• @create_event(target, condition) for custom conditions

Events created on the main workspace will trigger in all scenes. Pass in global_event=false to disable this.

Example:

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

@plp.on_update(ws, global_event=false)
def tick(w: plp.Workspace):
    if plp.Key.UP in w.input.key_downs:
        w.push_scene(s)

Scene and Modal Behavior

• If a modal is active, input is only routed to the modal tree
• Scene descendants are clipped to the scene rectangle for both drawing and hit-testing
• Workspace tracks scene/modal transitions with:
  • current_scene, previous_scene, scene_changed
  • current_modal, previous_modal, modal_changed
• Scenes can implement lifecycle hooks:
  • on_enter, on_exit, on_pause, on_resume

Input State

Read per-frame input from workspace.input:

• keys_pressed, key_downs, key_ups contain plp.Key values
• mouse_buttons_pressed, mouse_downs, mouse_ups contain plp.MouseButton values
• mouse_pos, mouse_delta, mouse_wheel
• text_input
• dt, runtime, quit
• key_held(key), key_up(key), key_down(key)
• mousebutton_held(mb), mousebutton_up(mb), mousebutton_down(mb)

Hover State

You can check the hovered objects and top hovered object using the helper methods in Workspace.

• is_mouse_top(element), just_hovered(element), just_unhovered(element) are for checking only the top hovered object.
• is_mouse_over(element), just_hovered_inclusive(element), just_unhovered_inclusive(element) are for checking all of the hovered objects.

event helpers come with these too.

• @on_hover(scope, hovered), @on_unhover(scope, hovered), while_hovered(scope, hovered) for only top.
• @on_hover_inclusive(scope, hovered), @on_unhover_inclusive(scope, hovered), while_hovered_inclusive(scope, hovered) for all.

These are useful because they can then be used to check if the user is clicking an object

obj = plp.UIPanel(plp.FRect(1, 1, 0, 0), plp.empty_rect(), (0, 0, 0))

@while_hovered(ws, obj)
def click_check(w: plp.Workspace):
    if w.input.mousebutton_down(plp.MouseButton.LEFT):
        print("LMB down!")