Skip to content

index.md

Latest commit

 

History

History
138 lines (95 loc) · 9.25 KB

index.md

File metadata and controls

138 lines (95 loc) · 9.25 KB
Raw

UI Layer

The UI layer is located in src/mpfb/ui/. It contains all Blender panels and operators for the MPFB addon. Panels define the interface elements that appear in Blender's 3D viewport sidebar, and operators implement the actions that buttons and menus invoke.

The UI layer sits at the top of the MPFB dependency hierarchy. It may freely use anything from the services and entities layers, but those layers do not depend on the UI. If you want to understand what MPFB actually does, read the services layer. If you want to understand what the user can see and click, read the UI layer.

Directory layout patterns

There are two main patterns for how feature directories are organized under src/mpfb/ui/.

Common pattern — main section with sub-sections:

src/mpfb/ui/
    create_assets/
        makeclothes/
        makeskin/
        maketarget/
        ...

The top-level directory (create_assets) defines a main panel visible in Blender's sidebar. Each subdirectory defines a sub-panel that appears nested inside it when the user expands it.

Standalone pattern — main section with no sub-sections:

src/mpfb/ui/
    model/

Here the directory defines panels directly, without any subdirectories grouping them into sub-sections.

Edge case — multiple panels but no subdirectories:

Some directories such as developer/ and haireditorpanel/ contain multiple panel definitions but are not split into sub-directories. These are treated as a single conceptual section. When documenting them, a single markdown file covers all panels in that directory.

Main sections

The table is sorted by the order the panels appear in, top to bottom.

bl_order Directory Blender panel name Category key Description
0 start_here/ Start here MODELCATEGORY Short introduction for new users: first steps, tutorial links, and asset library status
10 new_human/ New human MODELCATEGORY Creating new characters and importing from MakeHuman
20 model/ Model MODELCATEGORY Character morphing sliders and shape key management
30 rigging/ Rigging MODELCATEGORY Applying rigs, Rigify integration, rig helpers, and pose tools
40 apply_assets/ Apply assets MATERIALSCATEGORY Applying pre-made clothes and other assets to a character
50 presets/ Manage save files MATERIALSCATEGORY Saving and loading character presets and settings
60 operations/ Operations OPERATIONSCATEGORY Character manipulation: mesh operations, material operations, export, AI tools, and more
70 create_assets/ Create assets MODELCATEGORY Tools for authoring clothes, skin materials, morph targets, rigs, poses, and makeup
80 haireditorpanel/ Hair Editor HAIREDITORCATEGORY Experimental hair and fur editing interface
90 developer/ Developer DEVELOPERCATEGORY Developer and debugging tools
100 system/ System and resources DEVELOPERCATEGORY System configuration, directory management, and web resources

Category keys are string constants managed by UiService. They determine which sidebar tab a panel appears in. See UiService for the full list. Note that in the default single-tab configuration every category key resolves to the same tab label, so the category only decides where a panel would end up if the multi-panel mode were ever revived.

Every top-level panel declares an explicit bl_order, so that no panel's position falls out of the order the modules happen to be imported in. The values are spaced by ten to leave room for inserting panels later without renumbering. Sub-panels must not be given a bl_order to match their parent's — child panels are ordered within their own parent's list, independently of it. The bl_order values 1-10 used by the randomize sub-panels are an example of that, and are unrelated to the table above.

Blender only applies the declared order when a region has no saved record of a panel. Blend files saved with an older version of MPFB may therefore keep some of their previous panel order. This is expected; the intended order appears in fresh scenes.

The order is guarded by test/tests/eee_ui/panelorder_test.py, which will fail if a top-level panel is added without an explicit bl_order.

Top-level panel files

One panel file lives directly in src/mpfb/ui/ rather than in a subdirectory:

  • versionpanel.py — a fallback panel shown when the installed Blender version is too old to run MPFB. The rest of the UI layer is skipped entirely in that case.

Internal structure of a feature directory

Most feature subdirectories follow the same internal layout:

somefeature/
    __init__.py              # Imports all panels and operators; registers them with ClassManager
    somefeaturepanel.py      # One or more Panel classes (inherit from Abstract_Panel)
    operators/
        __init__.py
        someoperator.py      # One or more Operator classes (inherit from MpfbOperator)
    properties/              # Optional: JSON files defining scene-level properties
        someprop.json
    objectproperties/        # Optional: JSON files defining per-object properties
        someobjprop.json

When a feature needs to store configuration, it typically places JSON property definition files in a properties/ subdirectory and loads them with SceneConfigSet.from_definitions_in_json_directory(). Each JSON file defines one property (name, type, default, description, etc.). See SceneConfigSet and BlenderConfigSet for details.

Meta classes

Four foundational files in src/mpfb/ui/ are used by virtually every panel and operator in the addon. They are not features themselves, but infrastructure:

  • abstractpanel.py — Abstract_Panel, the base class for all panels
  • mpfboperator.py — MpfbOperator, the base class for all operators
  • mpfbcontext.py — MpfbContext, a helper that consolidates Blender context, scene properties, and object properties into one flat object
  • pollstrategy.py — the @pollstrategy decorator and PollStrategy constants, which inject poll() methods into panels and operators

These are fully documented in meta.md.

Two further files in src/mpfb/ui/ are shared helpers rather than base classes. They exist so that the same text is not maintained in two panels and allowed to drift apart:

  • weburls.py — the web addresses used by the UI, one named constant per address. Used by the "Web resources" sub-panel and by "Start here".
  • systemassets.py — determines whether the makehuman system assets are installed and up to date, and returns the lines to display about it. Used by "Apply assets" and by "Start here".

Registration

Every UI module's __init__.py calls ClassManager.add_class(SomePanel) and ClassManager.add_class(SomeOperator) during import. The ClassManager singleton (in src/mpfb/_classmanager.py) collects all classes into a list, then registers them all at once when src/mpfb/__init__.py:register() runs.

When validation is enabled, ClassManager.add_class() checks:

  • Operators must have a bl_idname that starts with "mpfb.". Example: bl_idname = "mpfb.load_clothes".
  • Operators must inherit from MpfbOperator.
  • Panels must have bl_label, bl_space_type, bl_region_type, and bl_category defined.
  • Panels must inherit from Abstract_Panel.

Reference tables

If you are looking for a specific operator see the operator reference table.

Section documentation

Documentation for individual UI sections:

  • Start here — the introductory panel new users meet first, and the preference which hides it
  • Model — character morphing sliders, phenotype controls, and shape key management
  • New Human — creating characters from scratch, from presets, from MHM files, or by importing from MakeHuman
  • Rigging — adding rigs, Rigify conversion, IK helpers, poses, and walk cycles
  • Apply Assets — browsing the installed asset library and loading clothes, skins, poses, topologies, and other assets onto a character
  • Create Assets — authoring clothes, skin materials, morph targets, rigs, poses, makeup layers, and vertex weights
  • Presets — saving and loading human character presets, skin material settings, eye material settings, and makeup configurations
  • Operations — mesh operations, material operations, pose tools, animation tools, facial shape keys, sculpt setup, and export copy
  • System — system diagnostics, web resource links, and directory quick-access
  • Developer — logging controls, node tree I/O, target file I/O, and code-generation tools for addon developers

Further reading

  • Code Structure Guide — how all four layers (services, entities, ui, data) relate to each other and how registration works end-to-end
  • Meta classes — Abstract_Panel, MpfbOperator, MpfbContext, pollstrategy
  • UiService — manages UI category names, preset lists, and other UI state