pgstudio 0.3.0

A GUI builder for pygame (using pygame_gui).

PgStudio 0.3.0

NOTICE: PgStudio is currently in early beta and far from complete. Please do not expect a bug-free experience or a “perfect” product at this stage. Updates will be rolled out periodically as the project continues to evolve and expand. We welcome feature suggestions and bug reports—feel free to share them with us on our Discord server at Taireru LLC ™ // PgStudio // #bugs-and-stuff.

a GUI editor for pygame using pygame_gui.

features (new in 0.3.0)

• Error dialogs: any time something goes wrong (save, export, rename, drawing, etc.), you get a UIMessageWindow explaining what happened.
• Theming: includes themes/pgstudio_theme.json. if present, PgStudio will load that and skin all UI elements (buttons, panels, labels, etc.).
• Undo/Redo: any add/delete/rename/property change is recorded. toolbar has “Undo” and “Redo” buttons.
• Custom event hookups: for Buttons, you can now pick on_click—choose a Script from your /scripts/ folder. on export (main.py), those scripts get imported and called when the button is pressed.

install

pip install pgstudio

quickstart

import pgstudio

pgstudio.configure(core="path/to/my_project_folder")
pgstudio.launch()

• this creates:

  • my_project_folder/objects.json
  • my_project_folder/scripts/
  • my_project_folder/images/
  • (optional) my_project_folder/themes/pgstudio_theme.json if you want theming

UI overview

1. Toolbar (top):

   • Undo: undo last change
   • Redo: redo last undone change
   • Save: force‐save objects.json now
   • Export: generate main.py with event hookups
   • New Prjct: wipes all objects, scripts, images (with confirmation)

2. Explorer (left):

   • shows a collapsible tree of all objects.
   • right‐click on blank → add root objects
   • right‐click on object → add child / rename / delete
   • arrow icon (▶/▼) toggles expand/collapse

3. Canvas (center):

   • drag objects around (nested transforms respected)
   • resize using bottom‐right corner
   • draw order by z_order (higher drawn on top)
   • click to select; selected object has yellow outline

4. Properties (right):

   • shows/edit properties for selected object:

     • abs_x, abs_y (auto-convert to relative under the hood)

     • w, h, visible, z_order, name

     • type-specific:

       • Rectangle: color picker
       • Button: text, font_size, color, on_click (choose from scripts)
       • Label: text, font_size, color
       • Image: file picker (choose image from filesystem)
       • TextInput: placeholder, text_color, bg_color
       • Script: “Edit Script” button (opens in default editor)

   • always has a Delete Object button

5. Error Handling:

   • if anything breaks (e.g. invalid number in property, file‐I/O fails, draw error), a UIMessageWindow pops up explaining it.

6. Theming:

   • if you place a themes/pgstudio_theme.json in the package (or modify it), PgStudio will load it and skin all UI.
   • sample theme changes button colors, panel BG, label text color, text entry style.

undo/redo details

• every time you call any method that mutates (add, delete, rename, update), PgStudio first snapshots the entire nodes dict as JSON.
• Undo pops the last snapshot, pushes the current snapshot onto the redo stack, and restores the old one.
• Redo does the reverse.
• Undo/Redo works for: add_object, delete_object, rename_object, update_properties, move_node.

custom event hookups

• only Buttons have event hookups currently. in the Properties panel for a Button, you see an on_click dropdown that lists “None” + every Script in /scripts/.

• if you choose a script (say MyScript), PgStudio stores node.events["on_click"] = "MyScript".

• on Export, main.py is generated so that:

    import scripts.MyScript as script_<button_id>
    ...
    if e.type == pygame_gui.UI_BUTTON_PRESSED and e.ui_element == elements['<button_id>']:
        script_<button_id>.run(elements['<button_id>'], event=e)
  

• thus, in your scripts/MyScript.py, just define a run(obj, event=None) function and do whatever you want.

theming

• the included themes/pgstudio_theme.json is a minimal example. you can customize fonts, colors, etc.
• if you remove or rename it, PgStudio falls back to the default pygame_gui theme.

error dialogs

• uses UIMessageWindow for anything from drawing errors, file I/O, invalid user input, etc.
• you’ll see a pop-up with a title and message.

how to develop locally

option 1

1. git-clone / download this repo.

2. cd to parent folder.

3. (optional) create a venv:

   python3 -m venv venv
   source venv/bin/activate  # or venv\Scripts\activate on Windows
   

4. pip install -e pgstudio/ ← installs in editable mode.

5. pgstudio my_test_project or from Python:

   import pgstudio
   pgstudio.configure("my_test_project")
   pgstudio.launch()
   

option 2

1. open your local terminal
2. run pip install pgstudio
3. open your local ide
4. make a new script and run:

   import pgstudio
   pgstudio.configure("my_test_project")
   pgstudio.launch()
   

enjoy building UIs without writing all the boilerplate—just drag, drop, click, export! 🚀🎨