Docs

These are some basic technical docs intended for developers. For more elaborate and user friendly documentation, see the docs hierarchy on the website.

Code structure

• Code Structure Guide — how the codebase is organized, for new developers

Development tooling

• Type checking — setting up and running pyright for static type checking

File formats

These are format descriptions for various files used by MPFB.

MakeHuman file formats

These describe the formats of files used by both MakeHuman and MPFB:

• MHM
• MHCLO
• MHMAT
• Target

MPFB JSON file formats

These describe JSON formats used internally by MPFB and for user presets:

• Rig definition — bone hierarchy and position strategies
• Vertex weights — bone-to-vertex weight assignments
• Pose — static bone rotations (system and user poses)
• Node tree / shader — Blender shader node network definitions
• Material settings — enhanced skin and eye parameter presets
• Target metadata — target categories and macro morph definitions
• Mesh metadata — vertex groups, mesh config, UV layers
• Human preset — complete character definition
• Miscellaneous presets — importer presets, makeup, ink layers

Services

API documentation for the service layer in src/mpfb/services/.

High level services

These are the top level services which abstract the functionality in MPFB. This is where you should start looking if you want to do something.

• HumanService — high-level character creation and serialization. This is the central service of MPFB.
• AssetService — asset discovery, caching, and pack management
• MaterialService — material creation and management
• TargetService — shape key and morph target management
• RigService — armature, bone, weight, and pose operations
• ClothesService — clothes fitting, rigging, and MHCLO management

System, infrastructure and configuration

These are services which are used throughout most of the code:

• LogService — logging and profiling infrastructure
• LocationService — file system path resolution
• SystemService — platform detection and system utilities

These are configuration-related helper classes:

• ConfigurationSet — abstract base for configuration management
• BlenderConfigSet — Blender entity property management (ie storing configuration on an object)
• SceneConfigSet — scene-level property configuration (ie storing configuration in the scene)
• DynamicConfigSet — object configuration with dynamic properties

Utility services

These are helper services:

• ObjectService — Blender object creation and management
• ModifierService — Blender modifier operations
• NodeService — shader node tree and node manipulation
• NodeTreeService — node tree interface socket utilities
• MeshService — mesh, vertex group, and spatial operations
• UiService — UI state and preset list management

Services for specific or experimental functionality

These services are either abstractions for a specific feature, or experimental. Unless you work with these specific topics, it is unlikely you will need them elsewhere in the code.

• AnimationService — BVH import and keyframe manipulation. Mostly experimental.
• ExportService — character copy creation, shape key interpolation, and modifier baking for export to external applications
• HairEditorService — Hair and fur asset management. Experimental and only useful for the hair editor.

Communication with MakeHuman

These are services and classes which are only relevant when interacting with a running MakeHuman instance.

• SocketService — MakeHuman socket server communication
• JsonCall — JSON-serializable function call model.

UI layer

The UI layer contains all Blender panels and operators. It lives in src/mpfb/ui/ and is documented in docs/ui/.

• UI Layer Overview — directory structure, registration pattern, and internal feature layout
• Meta Classes — Abstract_Panel, MpfbOperator, MpfbContext, and the pollstrategy decorator

Entities

Entity classes are in src/mpfb/entities/. Entities are data-oriented classes that encapsulate state and domain logic, in contrast to the stateless singleton services. In many cases, an entity class is a wrapper for a file format (see above).

Data structures and utilities

• MeshCrossRef — multi-table mesh cross-reference for efficient spatial and topological queries
• PrimitiveProfiler — lightweight named timing profiler for development use

Object property sets

• Object properties — GeneralObjectProperties, HumanObjectProperties, and SkeletonObjectProperties: module-level BlenderConfigSet singletons that attach namespaced custom properties to Blender objects

Clothes entities

• Mhclo — parser and serializer for MHCLO clothing files
• VertexMatch — automatic clothes-to-basemesh vertex mapping with 4-strategy fallback

Material entities

• MHMAT key system — type hierarchy and key catalog for MHMAT parsing (mhmatkeytypes.py, mhmatkeys.py)
• MhMaterial — parser and serializer for MHMAT material files
• MakeSkinMaterial — bridges MHMAT format with Blender node-based materials (MakeSkin workflow)
• EnhancedSkinMaterial — advanced skin shader with PBR and subsurface scattering support

Rig entity

• Rig — armature serialisation/deserialisation and JSON Blender round-trip, with positioning-strategy system

Rigging helpers

Yes it looks odd that each helper is a one-to-one class hierarchy. "Default" here is the "default" rig. The plan was originally to support other rigs too.

• AbstractRigHelper — base class providing Blender mode-switching utilities
• ArmHelpers / DefaultArmHelpers — IK helper bones and constraints for arms
• LegHelpers / DefaultLegHelpers — IK helper bones and constraints for legs
• EyeHelpers / DefaultEyeHelpers — eye-tracking IK bones and constraints
• FingerHelpers / DefaultFingerHelpers — grip and IK helpers for fingers
• RigifyHelpers / GameEngineRigifyHelpers — Rigify metarig conversion