Provide examples on how to use MPFB as a scripting API

[blackears]

I was wondering if MPFB has some sort of Python user interface that would allow me to create humans from a script? I'm working on a project where I'd like to write a script that can generate a variety of humans with varying parameters. I was looking through the MPFB source code, but it seems pretty complicated. I'm not even sure what I'd need to import to get a HumanService.

Is there some way to run MPFB purely from a script? If not, is that something you'd consider adding?

[joepal1976]

Actually, yes. It is perfectly possible to use MPFB's services layer as an API. All you need is to get around the quirk that blender extensions end up in an unknown module structure, and that you therefore can't do normal imports. But you can simply copy/paste the dynamic_import method provided here to get full access to the API. For example in the script tab:

import importlib, sys

def dynamic_import(absolute_package_str, key):
    """Quirk to get around blender's extension format's requirement that all imports must be relative"""
    for amod in sys.modules:
        if amod.endswith(absolute_package_str):
            mpfb_mod = importlib.import_module(amod)

            if not hasattr(mpfb_mod, key):
                raise AttributeError(f"Module {amod} does not have attribute {key}")

            return getattr(mpfb_mod, key)
    raise ValueError(f"No module found with name ending in {absolute_package_str}")


HumanService = dynamic_import("mpfb.services.humanservice", "HumanService")
TargetService = dynamic_import("mpfb.services.targetservice", "TargetService")
HumanObjectProperties = dynamic_import("mpfb.entities.objectproperties", "HumanObjectProperties")

# Simplest possible case
neutral_human = HumanService.create_human()
neutral_human.location = (-1, 0, 0)

# caucasian woman 
caucasian_woman = HumanService.create_human()
caucasian_woman.location = (1, 0, 0)

HumanObjectProperties.set_value("african", 0.0, entity_reference=caucasian_woman)
HumanObjectProperties.set_value("asian", 0.0, entity_reference=caucasian_woman)
HumanObjectProperties.set_value("caucasian", 0.0, entity_reference=caucasian_woman)
HumanObjectProperties.set_value("gender", 1.0, entity_reference=caucasian_woman)

TargetService.reapply_macro_details(caucasian_woman)

Obviously, there's a whole lot to get your head around for the finer details, but for creating some humans it isn't harder than this.

The entire API is documented here: https://github.com/makehumancommunity/mpfb2/blob/master/docs/index.md

You will probably benefit most from reading HumanService, TargetService and HumanObjectProperties if you want script human generation.

I've been meaning to create a tutorial about all this...

[blackears]

Thanks! That script works great?

How would you apply a skin texture and clothing? And add a rig? Is there a list of all the different properties you can set?

[joepal1976]

I've added some basic samples in https://github.com/makehumancommunity/mpfb2/blob/master/script_samples/index.md now. Can you check if these are enough for your needs?

[blackears]

This is really helpful!

I'm not able to create a rigify style rig. The notes seem to say that if I pass in the name "rigify.default" then it will create a Rigify style rig, but I get the error message

Python: Traceback (most recent call last):
  File "X:\biz\fiverr\2026\2026-04-12-watsonboba-washHands\experiments\mptb_create.blend\Text.001", line 40, in <module>
  File "C:\Users\mark\AppData\Roaming\Blender Foundation\Blender\5.1\extensions\blender_org\mpfb\services\humanservice.py", line 1472, in add_builtin_rig
    raise IOError("Could not find the rig file: " + rig_file)
OSError: Could not find the rig file: C:\Users\mark\AppData\Roaming\Blender Foundation\Blender\5.1\extensions\blender_org\mpfb\data\rigs\rigify\rig.default.json

I also put together this by combining the different scripts you provided. Aside from the rigify rig failing, it also failed to add the eyes. The eyes aren't set up in the assets folder with a brown.mchlo file - instead there is a high and low poly generic .mchlo file and several .mhmat variations. Not sure how I should use those.

import bpy
import importlib, sys

def dynamic_import(absolute_package_str, key):
    """Quirk to get around blender's extension format's requirement that all imports must be relative"""
    for amod in sys.modules:
        if amod.endswith(absolute_package_str):
            mpfb_mod = importlib.import_module(amod)

            if not hasattr(mpfb_mod, key):
                raise AttributeError(f"Module {amod} does not have attribute {key}")

            return getattr(mpfb_mod, key)
    raise ValueError(f"No module found with name ending in {absolute_package_str}")


HumanService = dynamic_import("mpfb.services.humanservice", "HumanService")
TargetService = dynamic_import("mpfb.services.targetservice", "TargetService")
HumanObjectProperties = dynamic_import("mpfb.entities.objectproperties", "HumanObjectProperties")
AssetService = dynamic_import("mpfb.services.assetservice", "AssetService")

# Simplest possible case
neutral_human = HumanService.create_human()
neutral_human.location = (-1, 0, 0)

# caucasian woman 
caucasian_woman = HumanService.create_human()
caucasian_woman.location = (1, 0, 0)

HumanObjectProperties.set_value("african", 0.0, entity_reference=caucasian_woman)
HumanObjectProperties.set_value("asian", 0.0, entity_reference=caucasian_woman)
HumanObjectProperties.set_value("caucasian", 0.0, entity_reference=caucasian_woman)
HumanObjectProperties.set_value("gender", 1.0, entity_reference=caucasian_woman)

TargetService.reapply_macro_details(caucasian_woman)

rig = HumanService.add_builtin_rig(caucasian_woman, "default")



# AssetService.find_asset_absolute_path() walks the configured asset roots looking for the
# requested filename under the given asset_subdir. It returns None if nothing was found.
mhmat_path = AssetService.find_asset_absolute_path("young_caucasian_female.mhmat", asset_subdir="skins")

if mhmat_path is None:
    raise RuntimeError(
        "Could not find young_caucasian_female.mhmat. "
        "Install the makehuman_system_assets pack and configure the assets directory in MPFB preferences.")

# Valid skin_type values are "ENHANCED_SSS" (default), "MAKESKIN", "GAMEENGINE" and "LAYERED".
# MAKESKIN produces a single, easy-to-inspect node tree that is closest to the raw .mhmat file
# and works the same across all renderers.
HumanService.set_character_skin(mhmat_path, caucasian_woman, skin_type="MAKESKIN")


# (subdir under the assets root, .mhclo filename, asset_type to assign)
assets = [
    ("eyes",      "brown.mhclo",       "Eyes"),
    ("eyebrows",  "eyebrow001.mhclo",  "Eyebrows"),
    ("eyelashes", "eyelashes01.mhclo", "Eyelashes"),
    ("tongue",    "tongue01.mhclo",    "Tongue"),
    ("teeth",     "teeth_base.mhclo",  "Teeth"),
    ("clothes",   "female_casualsuit01.mhclo",  "Clothes"),
    ("hair/braid01",   "braid01.mhclo",  "Hair"),
]

for subdir, fname, atype in assets:
    path = AssetService.find_asset_absolute_path(fname, asset_subdir=subdir)
    if path is None:
        print(f"Skipping {atype}: {fname} not found (makehuman_system_assets pack required)")
        continue
    HumanService.add_mhclo_asset(path, caucasian_woman, asset_type=atype)

[joepal1976]

The eye thing I thought I had fixed. It should indeed be either "low-poly.mhclo" or "high-poly.mhclo" instead of "brown.mhclo". ... I must've made the edit in the script editor and then failed to paste it to the github code.

I'll update this and make a coherent rigify example too.

[joepal1976]

@blackears : I've now added some more examples and fixed a bunch of stuff. There's a separate and full rigify example in there too.

Suggestions for additional examples to add are welcome.