Skip to main content

PyForgeUI

Ask DeepWiki Python 3.10+ License: MIT

PyForgeUI is a modular, zero-leak, game-ready GUI widget and container library built on top of Pygame. Designed around the ElementsFactory and UIManager patterns, it lets you build HUDs, RPG inventories, draggable windows, and multi-tab settings screens with cached font surfaces and clean event propagation.


Features

  • 18 Built-in Game Widgets & Containers:
    • Core Controls: Text, TextButton, PolygonButton, InputText, Image, ImageButton
    • Settings & Value Controls: CheckBox, ToggleSwitch, Slider, ProgressBar, RadioButton / RadioGroup, NumberSpinner, KeybindButton
    • Dropdowns & Scrolling: ComboBox (down, up, right, left) & ScrollBar (vertical & horizontal with mouse wheel support)
    • Containers & Layouts: Panel (draggable & clippable), StackLayout, GridLayout, TabContainer, Modal / DialogBox
    • Feedback: Automatic floating Tooltip with hover delay
  • High Performance (Zero Surface Leaks): Text and label surfaces are pre-rendered and cached (_update_surfaces()), avoiding per-frame font.render() calls.
  • Z-Order & Modal Input Blocking: UIManager handles top-down event consumption and blocks background clicks when a Modal is open.

Installation

From PyPI (once published)

pip install pyforgeui

Local Editable Install (for development or local projects)

pip install -e .

Quickstart

import pygame
from pyforgeui import ElementsFactory

pygame.init()
screen = pygame.display.set_mode((800, 600))
clock = pygame.time.Clock()

factory = ElementsFactory({"screen": screen})
ui = factory.create_UIManager()

panel = factory.create_Panel({
    "position": (200, 120, 400, 320),
    "title": "AUDIO & VIDEO SETTINGS",
    "draggable": True,
})

chk_vsync = factory.create_CheckBox({
    "position": (230, 175),
    "text": "Enable V-Sync",
    "checked": True,
    "tooltip": "Sync frame rate with monitor refresh rate",
})

sld_volume = factory.create_Slider({
    "position": (230, 245, 260, 14),
    "min_value": 0,
    "max_value": 100,
    "value": 80,
    "label": "Master Volume",
})

btn_apply = factory.create_TextButton({
    "position": (230, 310),
    "text": "Apply Changes",
    "command1": lambda: print("Volume:", sld_volume.get_value(), "VSync:", chk_vsync.get_value()),
})

for child in (chk_vsync, sld_volume, btn_apply):
    panel.add_child(child)

ui.add(panel)

running = True
while running:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False
        else:
            ui.events(event)

    screen.fill((20, 24, 32))
    ui.draw()
    pygame.display.flip()
    clock.tick(60)

pygame.quit()

Complete Interactive RPG Demo

Run the included multi-screen game UI showcase (Main Menu, Hero Loadout & HUD, and System Configuration):

python demo_game_ui.py

Running Tests & Building the Package

Run the automated test suite:

python -m unittest discover -s tests

Build .whl and .tar.gz distributions for PyPI:

pip install build twine
python -m build
twine upload dist/*

Metadata

Release files for pyforgeui 1.0.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 pyforgeui 1.0.0
File Size Uploaded Provenance Actions
pyforgeui-1.0.0.tar.gz 40.6 kB Without provenance Details for pyforgeui-1.0.0.tar.gz

Built distribution (wheel)

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

Total release size: 91.3 kB

Release files / pyforgeui-1.0.0.tar.gz

Download URL pyforgeui-1.0.0.tar.gz
Size 40.6 kB
Tags Source
SHA-256 checksum
How to use checksums
b1b85a0a09388c7668c8e4896b46e50c1965be0add96b59826314b8bb341f226
BLAKE2b-256 checksum
How to use checksums
45736027e0b425d8ec3482cc2e4bb3923fa47d19cfe2c10a2a3caa173ef2c705
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.0

Release files / pyforgeui-1.0.0-py3-none-any.whl

Download URL pyforgeui-1.0.0-py3-none-any.whl
Size 50.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e07e630d0294363923e8bac435400e0d6af4395b2a16dbc8dcf0d5009415f01e
BLAKE2b-256 checksum
How to use checksums
8e8878b3756cfe6a157ff01d2561106cc6b351e6d65c1e3d26940dc1c1aa0301
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.0

Security for pyforgeui 1.0.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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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

1.0.0 This release

2 release files No 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