puree-ui 0.0.7

XWZ Puree UI framework for Blender

A declarative UI framework for Blender addons and much more

Puree UI for Blender is a declarative framework that provides a web-inspired API for building user interfaces, addressing the limitations of Blender's native UI system in supporting complex interface architectures and providing enhanced flexibility.

Puree is built on top of ModernGL, TinyCSS2, and Stretchable to deliver a high-performance, GPU-accelerated UI engine with a familiar web development paradigm.

Key Features

Feature	Description
Declarative UI Design	Define your interface structure using TOML configuration files with HTML-like nesting
GPU-Accelerated Rendering	Leverages ModernGL compute shaders for real-time, high-performance UI rendering
Responsive Layouts	Automatic layout computation using the Stretchable flexbox engine
Interactive Components	Built-in support for hover states, click events, scrolling, and toggle interactions
Web-Inspired Architecture	Familiar paradigm for developers coming from web development

How it works

Puree follows a render pipeline inspired by modern web browsers:

1. Parse & Structure – UI components are defined in TOML files with a hierarchical container structure
2. Style Application – CSS files are parsed and styles are applied to containers with support for variables and selectors
3. Layout Computation – The Stretchable engine computes flexbox layouts with support for percentage-based sizing, padding, margins, and borders
4. GPU Rendering – A compute shader generates the final UI texture with gradients, rounded corners, shadows, and interaction states
5. Event Handling – Mouse, scroll, and click events are tracked and propagated through the component tree

This architecture allows for rapid UI prototyping and iteration while maintaining the performance requirements of real-time 3D applications.

[!NOTE] Read the full documentation for detailed guides, API references, and examples.

Quick Example

Here's a minimal example to get you started with Puree:

1. Download the latest release

2. Create your project structure:

   my_addon/x
       ├── static/
       │   ├── index.toml
       │   └── style.css
       └── __init__.py <-- your addon entry point
   

3. Define your addon manifest in blender_manifest.toml:

   Rename the blender_manifest.example.toml to blender_manifest.toml and modify to fit your addons metadata.

   schema_version      = "1.0.0"
   id                  = "your_addon_id"
   version             = "your_addon_version"
   name                = "your_addon_name"
   tagline             = "your_addon_tagline"
   maintainer          = "your_name"
   type                = "add-on"
   blender_version_min = "your_addon_version_blend_min"
   
   license = [
   "your_addon_license",
   ]
   
   platforms = [
   "windows-x64",
   "linux-x64",
   "macos-arm64",
   "macos-x64"
   ]
   
   wheels = [
   "./wheels/puree_ui-0.0.7-py3-none-any.whl"
   ]
   
   [build]
   paths_exclude_pattern = [
   "__pycache__/",
   "*.zip",
   "*.pyc",
   ".gitignore",
   ".vscode/",
   ".git/",
   ]
   

4. Define your addon entrypoint in __init__.py:

   Rename the __init__.example.py to __init__.py and modify to fit your addons metadata.

   import bpy
   import os
   from puree import register as xwz_ui_register, unregister as xwz_ui_unregister
   from puree import set_addon_root
   
   bl_info = {
       "name"       : "your_addon_name",
       "author"     : "your_name",
       "version"    : (1, 0, 0),
       "blender"    : (4, 2, 0),
       "location"   : "3D View > Sidebar > Your Addon",
       "description": "Your addon description",
       "category"   : "Your Addon Category"
   }
   
   def register():
       # Set the addon root directory so puree knows where to find resources
       set_addon_root(os.path.dirname(os.path.abspath(__file__)))
       # Register the framework
       xwz_ui_register()
       # Set default properties
       # ui_conf_path is relative to the addon root directory and
       # is required to point puree to the main configuration file of your UI
       wm = bpy.context.window_manager
       wm.xwz_ui_conf_path = "static/index.toml"
       wm.xwz_debug_panel  = True
       wm.xwz_auto_start   = True
   
   def unregister():
       # Unregister the framework
       xwz_ui_unregister()
       
   if __name__ == "__main__":
       register()
   

5. Define your UI in index.toml:

   [app]
       selected_theme = "default"
       default_theme  = "default"
   [[app.theme]]
       name         = "default"
       author       = "you"
       version      = "1.0.0"
       default_font = "NeueMontreal-Regular"
       styles       = ["static/style.css"]
       scripts      = []
       components   = ""
       [app.theme.root]
           style = "root"
           [app.theme.root.hello]
               style = "hello_box"
               text  = "Hello, Puree!"
   

6. Style it in style.css:

   root {
       width          : 100%;
       height         : 100%;
       display        : flex;
       align-items    : center;
       justify-content: center;
   }
   
   hello_box {
       width           : 300px;
       height          : 100px;
       background-color: #3498db;
       border-radius   : 10px;
       text-color      : #ffffff;
       text-scale      : 24px;
   }
   

7. Zip the files.

8. Install in Blender: Edit > Preferences > Add-ons > Install from disk

9. Done. If you open the latest version of Blender you have installed on your system you should see a puree tab in the N-panel of the 3D Viewport - click the button and you will see a blue rectangle with text.

Support & Issues

Getting Help

For questions and support, check out the docs or support guide.

Reporting Issues

Found a bug or have a feature request? Open an issue with:

• Clear description of the problem or feature
• Steps to reproduce (for bugs)
• Blender version and OS
• Relevant error messages or screenshots

Built With

   

   

       

Special thanks to the open-source community and the developers behind the projects that make puree possible.