How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/tipoli5890/unity-dev-skills --skill blender-character-rigBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
blender-character-rig — measure the mesh, compute the weights, prove the file
A generated character is a mesh and nothing else: no skeleton, no scale, a thin double shell in several islands. An auto-rigger wants standard proportions and one watertight body; automatic weights want a surface every bone can see. A short-limbed mascot with long ears gives neither.
A standard humanoid goes to `character-autorig` first — Auto-Rig Pro, headless, onto the humanoid contract. This skill is the hand-built fallback: a custom body that rig cannot take, or a mesh fitted to one clip pack's skeleton.
Start here — the request, and where it is answered
| The request or symptom | Read |
|---|---|
| "Rig this GLB" by hand: a mascot body the default auto-rig cannot take | the pipeline, then reference/import-and-survey.md |
| "Chibi / short limbs", "automatic weights failed" (bone heat on a double shell), "the ears tear when posed": the bone spec, radii, the positional rule, gradient chains, symptom → fix | reference/armature-and-skinning.md |
| "Fit my character to the mocap pack's skeleton": what may change, canonical and display scale, soles on the floor, hip width, the skin method by measured intersection | reference/fit-to-clip-skeleton.md |
A notch at the shoulder top in the bind pose, the A-pose mesh baked into the pack's T rest pose: a donor rig's weights (scripts/bcr_weight_donor.py), the bake (scripts/bcr_rest_bake.py), the gate against the modelled mesh (scripts/rest_gate.py) | reference/fit-to-clip-skeleton.md |
"Run Blender headless": stage layout (blender -b), gates JSON, exit 0/1/2, byte-identical FBX, a Unity lab outside the repo | reference/headless-pipeline.md |
| Registering the server, the cheapest probes, running a module through it (the stub, the reload order, the loader when Blender cannot read the skill directory), where a render really lands | reference/mcp-session.md |
Someone else's scene: collections, hiding, a second scene, translated UI names (KeyError 'Principled BSDF'), what to report | reference/scene-discipline.md |
| Importing the GLB, origin, height, facing, the weld, reading landmarks from slices and boxes | reference/import-and-survey.md |
| An image-to-3D GLB's inward-facing inner shell cut off before import, by visibility (host, no Blender) | reference/import-and-survey.md, scripts/shell_strip.py |
A prop in a hand: grip measured from the prop, the sanity ratio, bone parenting; a shield on the forearm (mount: forearm) | reference/prop-on-bone.md |
| Poses in armature axes, keying an action, the contact probe, chunked renders, GIF and contact sheet | reference/action-and-preview.md |
| The ship track's game mesh before rigging: regenerate at the preset, or retopology, UVs and a rebake from the showcase, gated in one headless run; its base colour repainted after the bake (S5b) | reference/game-mesh.md, scripts/game_mesh.py |
A character in parts (three): register the generated head onto the anchor, split its hair, cut, seam, gates; the hair bound by character-autorig autorig.py all --hair; fine: the hands attached under the sleeve | reference/part-assembly.md, scripts/assemble_parts.py, scripts/part_math.py, scripts/hand_parts.py |
| The ship track's mesh from parts: one mesh, one material, one atlas per map, before the rig | reference/part-assembly.md §8, scripts/ship_merge.py |
| Exporter options, clip naming, export FBX and prove it by re-import, the Unity check | reference/fbx-export.md |
| "LOD spikes": lighter skinned levels on one skeleton — hidden shells, shard props, normals, boundary weights, names Unity will not turn into a LODGroup | reference/skinned-lod.md |
| A worked example: the plush runner with long ears and a mallet, every step | reference/worked-example.md |
| The call contract of each module (its docstring) | scripts/bcr_*.py, scripts/rig_gate.py, scripts/rest_gate.py, scripts/frames_preview.py |
Nothing here is placed by eye or solved. Joints are read from slices of the mesh, weights are computed from where each vertex is, the swing is measured at the contact frame before it is rendered, and the FBX is imported back and compared.
Every step is one call to a module in scripts/ that returns a dict of gates: through the MCP server of a Blender the user already has open, for one character explored by hand; or from a stage script under blender -b --factory-startup --python, for a character rebuilt the same way every time. Every module runs unchanged headless (reference/headless-pipeline.md); through the server, a short stub imports and reloads it and result is the dict it returns (reference/mcp-session.md).
One clip pack supplies the motion? Fit, do not build. Move the pack's skeleton onto the mesh once (names, parents and rest rotations kept) and the clips play unchanged: reference/fit-to-clip-skeleton.md. Building a skeleton from landmarks is for a custom body.Working contract
- The user's Blender, the user's file. Installing Blender, the add-on or the server is the
user's, on request only. Never save unasked; say whether the file is saved when handing back.
- List the server's tools, do not recall them. "Unreachable" is not "absent": ask whether
Blender is open and connected before concluding anything.
- Work additively. New objects go in their own collection. Hide instead of delete; add a
camera, light or world instead of editing the user's. Report every non-additive change.
- Find nodes by type, not by name. With a non-English UI
nodes["Principled BSDF"]raises
KeyError; bcr_common.node_of looks a node up by bl_idname.
- `pass` covers one step. Read a failed gate's
valueagainst itslimit, change one
parameter and rerun before the next step. Calls are idempotent by name, and bcr_import_prep and bcr_attach reuse what exists and ignore new parameters: remove the object, or put the prop back, before a rerun. A call that raises removes what it created; edits to datablocks that already existed are not undone.
- Headless, the stage owns its files. It reads the previous stage's output and writes its own
.blend and gates JSON; it never opens the user's file for writing. Exit 0 pass, 1 a gate failed, 2 refused input (the rest-bake scripts: 2 failed, 3 unreadable, 1 refused); two runs give the same mesh hashes and FBX bytes.
1. The pipeline
In order. A row is done when its gates pass or, where it says picture, when someone has looked.
| # | Step | Module / op | Passes when |
|---|---|---|---|
| 1 | Probe the session | The server's blend-file and objects summaries | File path, save state, collections, active object and mode are known before any code runs |
| 2 | Import and prep | bcr_import_prep | one_mesh, identity_scale_rotation, origin_at_base, weld_kept_faces; height as asked |
| 3 | Survey | bcr_survey | has_vertices, empty_boxes; parts reads 2 at the legs and ears, 3 where the arms hang |
| 4 | Armature | bcr_armature | bone_count, zero_length_bones, roots, pose_bones_not_xyz, deform_bones_without_radius |
| 5 | Skin | bcr_skin | unweighted_vertices 0, max_influences ≤ 4, weight_sum_error < 1e-4, deform_bones_without_vertices; no bone with a near-empty dominant_vertices |
| 6 | Extreme-pose test | bcr_pose op apply → bcr_preview still → bcr_pose op reset | Picture: nothing torn into strips, no torso dragged by an arm, no folded crease; then pose_is_rest |
| 7 | Prop on the hand bone | bcr_import_prep (weld_distance: None), then bcr_attach at the rest pose | handle_radius_ratio ≤ 0.15, world_drift_after_parenting < 1e-4 |
| 8 | Key the action | bcr_pose op key; op key_object for a target that reacts | slot_assigned, fcurves ≥ 3 per keyed bone, first_equals_last when loop is set |
| 9 | Probe contact, then preview | bcr_probe; bcr_preview in chunks; scripts/frames_preview.py on the host | distance_to_target ≤ 0.05, direction_z ≥ −0.8; frames_missing, settings_restored; exit 0; picture: the GIF and the contact sheet |
| 10 | FBX export, re-import, gate | bcr_fbx ops snapshot → export → reimport → discard, with scripts/rig_gate.py on the two snapshots | finished, file_bytes, one_armature; exit 0 on bones, parents, bone_positions, groups, bone_parents, influences, scale, action |
Numbers cannot close steps 6 and 9: a mesh passes every weight gate and still tears; a swing lands on a target that stands between the camera and the character.
Discipline
- Weights are judged in an extreme pose, never at rest. At rest every weighting looks correct.
- Probe before rendering. The probe says by how much a swing misses; a render says that it does.
- Do not trust a sign you have not seen. Rotations are steps in armature axes, applied in the
order written. Before keying, apply one step and probe which way the point moved.
- Keep the inner shell and every island in the scene; cull back faces instead. To drop the twin,
scripts/shell_strip.py cuts it from the GLB before import (reference/import-and-survey.md).
- "FINISHED" proves a file, not a rig. Only the re-import and
rig_gate.pydo. - Decide the clip name before Unity. One action exports as a take named after the scene;
all-actions writes every action in the .blend as <rig>|<action>.
- State the limits when handing back: FK only, feet planted, single-handed, a hand that does
not close around the handle.
Scope — what this skill does NOT do
| Not here | Go to |
|---|---|
| The source image and the four-view sheet (A-pose, thick ears, no held prop) | codex-visual |
| Generating the GLB and gating its triangle and texture budget | comfyui-asset-generation |
| Mixamo for standard proportions; the Unity FBX importer, Avatar, Animator, PBR maps | unity-rigged-character |
| Static props that need no skeleton | unity-3d-models |
| Moving the character in Unity: controller, grounding, the Animator bridge | unity-3d-controller |
| Retargeting stock or purchased clips onto a rig, a library of them, a grip held across clips | blender-retarget |
| IK, foot planting, facial rigs, cloth or physics bones | Not covered — this is FK on a hand-specified skeleton |
| Installing Blender, the add-on or the MCP server | The user's, on request only |
| The character's stage order: preview or ship track, the game mesh before the rig | game-character-pipeline |
| A humanoid rigged headless onto the humanoid contract: Auto-Rig Pro from measured markers, the mesh and deformation gates | character-autorig |
| Clips from two-camera video onto the contract, contact bake | humanoid-motion |
| Proving the action plays in the running game | unity-debug |