BA QuickRig PMX

English | 简体中文

BA QuickRig PMX is a Blender add-on for one repeatable workflow: take an anime humanoid FBX that already has an armature and skin weights, manually remove weapons/props/effects, mark the remaining character and Halo meshes, then build an MMD-compatible rig and export PMX through MMD Tools.

The add-on uses the source FBX skeleton as proportion and skinning evidence. It does not need an AI model, GPU, external Python environment, or network access.

Requirements

• Blender 4.2 LTS or newer (tested with Blender 5.1.2)
• MMD Tools v4.x for MMD metadata and PMX export
• A rigged, approximately standard two-arm/two-leg humanoid FBX

Rig strategies

• Retarget Existing is the smaller, stable rig. It maps the essential body chain, preserves weighted secondary bones, and is suitable for varied anime humanoids.
• PMX Standard Full Body (Experimental) fits the mandatory 109-bone MMD core, then standardizes every corresponding helper/deform bone against an exact 253-bone metadata contract derived from the refined Mika(sw) PMX. Existing character weights and rest geometry remain authoritative.
• Reference Consensus (Legacy) keeps the previous six-model 109-bone profile available as a rollback option.

The reference PMX files are development inputs only. The installed add-on ships only a factual JSON skeleton profile; it contains no reference mesh, material, texture, morph, rigid-body, joint, or vertex-weight data.

Install MMD Tools

In Blender 4.2+:

1. Open Edit -> Preferences -> System and allow online access if required.
2. Open Edit -> Preferences -> Get Extensions.
3. Search for MMD Tools and install/enable it.
4. In BA QuickRig's N-panel, click Doctor. MMD Tools: OK enables PMX export.

BA QuickRig does not bundle, patch, or reimplement MMD Tools.

Install BA QuickRig

1. Download ba_quickrig_pmx-0.3.1.zip from GitHub Releases, or build it locally under dist/.
2. In Blender open Edit -> Preferences -> Add-ons/Extensions -> Install from Disk.
3. Select the zip and enable BA QuickRig PMX.
4. Open the 3D View sidebar with N, then choose BA QuickRig.

Build the zip from source:

python scripts/build_addon.py

Import FBX and manual cleanup

Import the FBX with Blender's importer or your preferred FBX importer. Before running BA QuickRig, manually delete weapon, gun, magazine, prop, unrelated effect, and other unwanted Mesh objects. Keep body, face, eyes, hair, clothes, accessories, and Halo.

The add-on deliberately does not guess which Mesh is a weapon. Obsolete bones can be omitted reliably only after their associated unwanted mesh is deleted.

Shortest workflow

1. Select all remaining non-Halo character Mesh objects and click Mark Selected as Character.
2. Select one or more Halo Mesh objects and click Mark Selected as Halo.
3. Choose PMX Standard Full Body (Experimental). Leave Reference Profile empty to use the bundled exact 253-bone metadata contract.
4. Click Analyze. Review Bone Mapping Debug if the state is REVIEW_REQUIRED.
5. Click One-Click QuickRig, then Validate.
6. Set Output Directory and Model Name, then click Export PMX.

Output is written as:

output/
`-- CharacterName/
    |-- CharacterName.pmx
    |-- textures/
    `-- baq_report.json

If a PMX already exists the add-on chooses CharacterName_v2.pmx, then _v3, and so on. It never silently overwrites a PMX.

What One-Click QuickRig does

Both strategies:

• Analyze marked objects, armature modifiers, groups, bones, weights, materials, and transforms.
• Score body semantics using name aliases (50%), hierarchy (20%), position (20%), and surviving weight evidence (10%).
• Stop before output mutation when an essential semantic is below the default 0.65 confidence threshold.
• Link originals into BAQ_SOURCE, deep-copy Mesh data/materials into BAQ_OUTPUT, and modify only tagged generated objects.
• Bake OUTPUT transforms while checking that world geometry did not move.
• Preserve weighted secondary hair/clothes/accessory bones and omit unweighted obsolete bones.
• Limit, normalize, and repair weights on generated meshes.
• Create 頭 -> 光輪親 -> 光輪, bind Halo vertices only to 光輪, and verify that the rest-pose Halo geometry did not jump.
• Configure MMD Tools metadata/display frames and write baq_last_run.log plus baq_report.json.

PMX Standard Full Body additionally:

• Fits the exact mandatory 109-bone MMD core to source ankle/head height and left/right/forward axes.
• Matches the remaining 144 standard entries one-to-one: exact names first, then safe normalized aliases such as Bip001 and bone_. Missing unweighted parents required by a matched chain are synthesized automatically.
• Classifies character-specific entries that do not exist in the source as not applicable. It does not fabricate weights for absent face, Halo, clothing, breast, or weapon bones.
• Snaps recognized major joints and named finger/twist controls to source joint locations; unmatched standard controls keep statistically robust reference positions.
• Uses the standard leg/foot chains as unweighted controls and the profile 足D/ひざD/足首D/足先EX chains for the actual lower-limb mesh weights.
• If a source ankle or toe is missing, fits the missing control/deform bones and conservatively redistributes only nearby lower-leg/foot weights; the source FBX remains untouched and the repair count is written to baq_report.json.
• Copies other weighted source bones into a hidden, non-controllable deform layer. Direct matches are parented under their MMD control; secondary chains retain their nearest preserved source ancestry.
• Recreates four PMX IK chains (左足IK, 右足IK, 左つま先IK, 右つま先IK). Toe.head is used as the forefoot pivot even when source Foot/Toe endpoints are disconnected, and both standard/D lower-limb chains are forced closed at rest before applying reference transforms, axes, order, and visibility.
• Keeps normalized Blender bone keys separate from exact Japanese PMX names, including full-width foot/toe ＩＫ and finger digits required by common VMD files.
• Validation includes Foot IK Rest Pose, so an open chain cannot pass while Blender silently pre-poses and twists the shoes; incompatible standard VMD bone names are also a hard validation error.

Run Delete Output and rebuild at any time. Re-running does not accumulate .001 generated bones and never edits the source FBX objects/data.

Mapping and custom profiles

For an unusual source rig, create a mapping override JSON:

{
  "HEAD": "Bone_047",
  "LEFT_HAND": "Bone_021"
}

Choose it under Mapping Override. Overrides take priority and receive confidence 1.0.

PMX Standard mode normally uses presets/mmd_pmx_standard_v1.json. A developer can select a compatible metadata-only JSON under Reference Profile. The old presets/baq_chibi_consensus_v1.json remains available through the legacy strategy. See docs/REFERENCE_TEMPLATE.md for extraction rules and limitations.

Testing

Pure Python:

python -m unittest discover -s tests -p "test_*.py" -v

Stable rig path:

blender --background --python scripts/run_blender_tests.py

PMX Standard Full Body path:

blender --background --python scripts/run_reference_blender_tests.py

The fixtures are generated from primitives. No Blue Archive game asset is included.

Troubleshooting

Buttons are not visible

Open a 3D Viewport, press N, select the BA QuickRig tab, and expand the main BA QuickRig PMX section. The separate Bone Mapping Debug section contains diagnostics, not the workflow buttons.

REVIEW_REQUIRED

Open Bone Mapping Debug. Lower the confidence threshold only when the shown source bones are correct; otherwise provide mapping_override.json.

Reference profile invalid

Click Doctor. The bundled profile should report mmd_pmx_standard_v1 with 109 core and 144 optional bones. Clear Reference Profile to stop using an incompatible custom JSON.

No Source Armature

Verify marked Character meshes still have an Armature Modifier pointing at the FBX armature, or are parented to it.

Unweighted-vertex warning

Repairs over 1% of a mesh deserve manual inspection. The report records the exact repair count; validation never accepts remaining unweighted vertices.

MMD Tools not found

Rig creation and analysis still work. Enable MMD Tools v4.x and run Doctor; PMX setup/export remains disabled until detected.

Feet remain locked after importing VMD

Models exported before 0.3.1 may contain half-width foot IK names that do not match standard VMD channels. Install 0.3.1, run Delete Output, rebuild the PMX Standard rig, and export a new PMX. Existing PMX files are not modified in place.

Fingers or physics

Official Bip001 L/R Finger0..4, common twist names, and standardized Bip001 /bone_ helper prefixes are handled by the reference matcher. Nonstandard finger naming may require an override or manual review. Automatic skirt/hair rigid bodies, complex cloth physics, morph creation, and artistic material conversion remain outside this version.

License and third-party boundaries

BA QuickRig PMX is MIT licensed. MMD Tools (GPLv3) and mmd_helper (GPLv3) remain separate upstream projects. See docs/RESEARCH.md for source/API research.