Model requirements
Most failed rigs are input problems, and the common ones are predictable. Ten minutes spent here will save you more than any parameter tuning.
The short checklist
Your mesh should be a single connected character, facing +Z, standing in a T-pose or A-pose, under 300k faces, with limbs that do not interpenetrate the body.
Orientation
The rigger expects the character to face +Z (toward the viewer in most engines' default front view). Getting this wrong produces a rig that looks structurally plausible but animates sideways, which is confusing to debug because nothing errors.
If your model faces another way, correct it on the way in with rotation_y rather than re-exporting:
| Model faces | rotation_y |
|---|---|
| +Z (correct) | omit, or 0 |
| +X | -90 |
| −X | 90 |
| −Z (away) | 180 |
Pose
T-pose is best: arms straight out to the sides, legs straight, palms down. A-pose (arms at roughly 45°) also works well.
Avoid rigging a character already in a dynamic pose. A crouching or running mesh gives the model contradictory evidence about where joints belong, and the resulting rig will fight every animation you apply.
Topology
One connected mesh is ideal. Separate accessories (a sword, a hat) are usually handled, but detached pieces far from the body can confuse joint prediction.
Watertight is better than not. Holes and non-manifold geometry degrade weight binding around the defect.
Avoid interpenetrating limbs. Arms fused to the torso, or thighs merged together, make it impossible to separate the influence of neighbouring bones, and you get weights that drag the body when a limb moves.
Density matters less than you would think. Anywhere from a few thousand to a couple hundred thousand faces works. Very sparse meshes (under about 1,000 vertices) can be unreliable, and anything over 300k faces is rejected.
Scale and units
Scale is not critical: the rigger normalises internally. What matters is that the character is a plausible single character rather than, say, a character standing on a large terrain mesh, which shifts the apparent proportions and misplaces joints.
Materials and textures
For GLB, everything travels in one file and comes back intact.
For OBJ, geometry only. Send a .zip containing the .obj, its .mtl, and the textures if you want materials preserved.
For FBX, embedded textures work; externally referenced ones will not resolve, since the rigger only fetches the one URL you provide.
STL carries no UVs or materials at all. You will get a correctly rigged but untextured result.
Body plan
Set rig_type to match your character. Submitting a quadruped as biped does not error; it produces a bad rig, because the model looks for a humanoid layout and finds four legs where it expected two.
rig_type | Use for |
|---|---|
biped | Humans, humanoids, most bipedal creatures |
quadruped | Dogs, horses, cats, most four-legged animals |
avian | Birds, winged creatures |
serpentine | Snakes, worms, tentacled forms |
aquatic | Fish, marine life |
hexapod / octopod | Insects, spiders |
others | Anything that fits none of the above |
When a rig fails
The error field on a failed rig names the cause. The most common are a mesh that could not be read (wrong format, or a corrupted file), a mesh above the face limit, and geometry too sparse or too fragmented to infer a skeleton from. Errors covers each and what to do about it.
If Fast fails on a mesh you believe is sound, retry the same mesh on the Pro engine before concluding the model is unriggable. They fail on different inputs.