Skip to main content

puigame

UI widgets for pygame-ce: buttons, labels, and panels, placed by anchors and styled by themes.

Status: alpha. The API may change in any 0.x release.

Install

pip install puigame

puigame needs Python 3.11+ and pygame-ce 2.5.8+. It uses pygame-ce, not pygame, and the two cannot be installed together.

Quick start

A window with one button, which quits (examples/minimal.py):

import pygame as pg

from puigame import UI, Button, DrawnSkin


def main() -> None:
    """Open a window and run the example until it is closed."""
    pg.init()
    screen = pg.display.set_mode((640, 360), pg.SCALED)
    pg.display.set_caption("puigame minimal demo")

    ui = UI(size=screen.size)

    Button(
        ui.root,
        size=(64, 30),
        skin=DrawnSkin(),
        text="QUIT",
        on_click=lambda _button: pg.event.post(pg.Event(pg.QUIT)),
    )

    clock = pg.time.Clock()
    running = True

    while running:
        clock.tick(60)

        for event in pg.event.get():
            if event.type == pg.QUIT:
                running = False

            ui.handle_event(event)

        ui.update()

        screen.fill("black")
        ui.draw(screen)
        pg.display.flip()

    pg.quit()


if __name__ == "__main__":
    main()

For more, see examples/custom_theme.py and examples/showcase.py.

Running a UI

Each frame, the game passes every event to ui.handle_event(), then calls ui.update(), then ui.draw(surface), in that order. Pass every event, not only mouse events: the UI needs window events such as WINDOWLEAVE to keep highlights and presses right, and it never polls pygame itself.

handle_event() returns whether the UI consumed the event. A click on a button or panel is consumed, so the game can ignore it:

for event in pg.event.get():
    consumed = ui.handle_event(event)

    if event.type == pg.QUIT:
        running = False

    elif not consumed and event.type == pg.MOUSEBUTTONDOWN:
        ...  # a click on the game world, not on the UI

Mouse motion, wheel, and window events are never consumed.

For a display opened with pg.SCALED, create the UI with the display's own size, screen.size, not the window's.

Widgets

  • Button: a clickable widget with text.
  • Label: text.
  • Panel: a background for its children, which by default stops clicks reaching the widgets and game below it.
  • Container: an invisible widget that groups and places its children.

Each widget is created with its parent, ui.root for a top-level widget, and placed against it: anchor is the point on the widget, parent_anchor the point on the parent it is matched to (the same point by default), and margin and offset move it from there. To place a group of widgets together, create them under a Container (or a Panel, for a background) that is itself under ui.root; a UI always covers its whole surface. Buttons and panels take a skin: DrawnSkin() draws them in the theme's style, and NoSkin() draws nothing.

Responding to clicks

A button's on_click is called with the button, from inside handle_event(). To keep game logic in the game loop, post an event and handle it there:

TOGGLE_PAUSE = pg.event.custom_type()

Button(
    ui.root,
    size=(96, 30),
    skin=DrawnSkin(),
    text="PAUSE",
    on_click=lambda _button: pg.event.post(pg.Event(TOGGLE_PAUSE)),
)

A key binding can then post the same event, so the button and the key share one handler.

Themes

A theme is a base style plus, for each state, the fields that state changes. The simplest way to make one is to copy the default base style with dataclasses.replace(), then write an override for each state that should look different:

from dataclasses import replace

from puigame import DEFAULT_THEME, UI, State, StyleOverride, Theme

theme = Theme(
    base_style=replace(DEFAULT_THEME.base_style, body_colour=(150, 0, 0, 255)),
    style_overrides={
        State.HIGHLIGHTED: StyleOverride(
            halo_colour=(255, 165, 0, 255),
            halo_thickness=6,
        ),
        State.PRESSED: StyleOverride(
            body_colour=(50, 0, 0, 255),
            text_offset=(0, 1),
        ),
    },
)

ui = UI(size=screen.size, theme=theme)

An override lists only the fields that differ, and the rest come from the base style. style_overrides replaces the default theme's overrides rather than adding to them, so a state left out, such as DISABLED above, looks the same as the base style. examples/custom_theme.py restyles the default theme this way, with overrides for the disabled, highlighted, and pressed states.

When several states apply at once, their overrides are applied in a fixed order, lowest precedence first: CHECKED, HIGHLIGHTED, PRESSED, EDITING, DISABLED. If two states set the same field, the later one wins, whatever order style_overrides lists them in.

Themes are frozen, and a UI's theme is set when it is created.

Text placement

Text is centred on its capitals. It is placed by a box that runs from the top of the first line's capitals to the last line's baseline, measured from the font, so text looks centred in any font and at any size with no offset, and descenders hang below the box.

text_horizontal_extent chooses how wide that box is:

  • TextHorizontalExtent.INK: from the first drawn pixel to the last. This suits pixel fonts like Neb0Font, whose spacing is all on one side of each glyph, and is what the default theme uses.
  • TextHorizontalExtent.LOGICAL: the font's own spacing, as in most text layout. Leading spaces count, and trailing spaces do not.

text_offset is for deliberate nudges, such as moving pressed text down 1 pixel.

Limitations in v0.1

  • Neb0Font and NebMon0Font cover printable ASCII only. Other characters, such as £ or é, are drawn as a placeholder box; use BundledTypeface.PYGAME_DEFAULT or a font file of your own for them. Both are pixel fonts, crisp only at sizes that are multiples of 6: Neb0Font (NEB0FONT) is proportional with tabular digits, and NebMon0Font (NEBMON0FONT) is its monospace version.
  • Multi-line text is left-aligned.
  • Subclassing widgets is not supported. Compose them instead.
  • The first click on an unfocused window is dropped. By default, SDL uses the click that focuses a window and does not pass it on, so the first click after switching to the game does not reach a button. To pass it on, set the hint before creating the window: os.environ["SDL_MOUSE_FOCUS_CLICKTHROUGH"] = "1". puigame leaves this choice to the game. This is untested on Windows.

Contributing

See CONTRIBUTING.md for setting up, running the checks, and commit messages.

Authorship

All code in puigame is written by hand. Documentation, including this README, the docs/ folder, and the docstrings in the code, is first drafted with AI assistance and then checked by hand.

License

MIT

Metadata

Release files for puigame 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for puigame 0.1.0
File Size Uploaded Provenance Actions
puigame-0.1.0.tar.gz 38.6 kB With provenance Details for puigame-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for puigame 0.1.0
File Interpreter ABI Platform Actions
puigame-0.1.0-py3-none-any.whl Python 3 none any Details for puigame-0.1.0-py3-none-any.whl

Total release size: 90.7 kB

Release files / puigame-0.1.0.tar.gz

Download URL puigame-0.1.0.tar.gz
Size 38.6 kB
Tags Source
SHA-256 checksum
How to use checksums
52f434306533391e51b62592f9706839006709c3a44430fca25ad2f54c29680a
BLAKE2b-256 checksum
How to use checksums
e0a92942e3dadc1bfd8772cc1923b38dd611dfdaca1b2f457a8022e9a528f243
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Release files / puigame-0.1.0-py3-none-any.whl

Download URL puigame-0.1.0-py3-none-any.whl
Size 52.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
811497343c1176312c42810c09169e05c8885a15368867fb2e33e143c10448f3
BLAKE2b-256 checksum
How to use checksums
b8305c59910ddb4a06e8f2dc240523c04b6c81f86344b93640eddf90c2a7d967
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Security for puigame 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for puigame-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page