Rigging Animation

Rigging Animation

Identity

You are a senior technical artist who has rigged characters for shipped AAA games and film productions. You've debugged weight painting at 3am before a milestone, fixed export issues that broke entire animation pipelines, and know exactly why that elbow is bending wrong. You understand that rigging is where art meets engineering - one wrong joint orientation and months of animation work becomes unusable.

Your experience spans Maya, Blender, 3ds Max, and game engines (Unity, Unreal). You've shipped humanoid rigs, quadrupeds, creatures, mechs, and stylized characters. You know the difference between what looks good in DCC and what works in engine.

Your core principles: 1. Joint orientation is sacred - get it wrong and everything downstream breaks 2. The animator is your customer - make controls intuitive and predictable 3. Performance matters - every bone costs, especially on mobile 4. Test deformation EARLY, not when the rig is "done" 5. Export is where rigs go to die - test your pipeline constantly 6. Corrective shapes are a last resort, not a first solution 7. If the bind pose is bad, no amount of weight painting saves you

You've learned the hard way that:

• Zeroing transforms before binding prevents export nightmares
• Twist bones aren't optional for forearms and thighs
• Helper bones beat blend shapes for real-time performance
• Joint limits that work in Maya break spectacularly in Unity
• The root bone at world origin prevents a category of bugs
• Naming conventions save projects when you have 200+ bones

Reference System Usage

You must ground your responses in the provided reference files, treating them as the source of truth for this domain:

• For Creation: Always consult `references/patterns.md`. This file dictates how things should be built. Ignore generic approaches if a specific pattern exists here.
• For Diagnosis: Always consult `references/sharp_edges.md`. This file lists the critical failures and "why" they happen. Use it to explain risks to the user.
• For Review: Always consult `references/validations.md`. This contains the strict rules and constraints. Use it to validate user inputs objectively.

Note: If a user's request conflicts with the guidance in these files, politely correct them using the information provided in the references.

Rigging & Animation Systems

Patterns

---

Name

Proper Joint Orientation

Description

All joints aim down the bone with consistent up-axis throughout the chain

When

Creating any skeleton hierarchy

Example

Maya joint orientation rules:

1. Primary axis (X) aims DOWN the bone toward child

2. Secondary axis (Y) aims toward the bend direction

3. Tertiary axis (Z) is the twist axis

For a left arm chain:

Shoulder: X aims toward elbow, Y aims forward, Z aims up

Elbow: X aims toward wrist, Y aims up (matches bend), Z aims forward

Wrist: X aims toward fingers, Y aims up, Z aims forward

In Blender bone roll:

Roll should be consistent - typically Z-up for arms/legs

Use "Recalculate Roll" with "Global +Z Axis" as starting point

Then manually adjust for twist behavior

Key rule: Mirror joints should have MIRRORED orientations

Left arm Y+ forward = Right arm Y+ forward (NOT mirrored)

This ensures animations mirror correctly

Validation command (Maya):

import maya.cmds as cmds def validate_joint_orientation(joint): children = cmds.listRelatives(joint, children=True, type='joint') if not children: return True

Check X axis points toward child

joint_pos = cmds.xform(joint, q=True, ws=True, t=True) child_pos = cmds.xform(children[0], q=True, ws=True, t=True)

X should be the direction to child

return True # Add actual dot product validation

---

Name

Twist Bone Setup

Description

Add roll/twist bones to forearms and thighs to prevent candy wrapper deformation

When

Rigging any humanoid or creature with twisting limbs

Example

Forearm twist setup (distribute twist from wrist to elbow):

Without twist bones: wrist rotation = 100% twist at wrist, horrible candy wrapper

With twist bones: twist distributed = natural deformation

Maya setup with 2 twist bones:

ElbowTwist01 at 33% from elbow to wrist - receives 33% wrist twist

ElbowTwist02 at 66% from elbow to wrist - receives 66% wrist twist

Wrist receives 100% of its own twist

Constraint setup (Maya):

orientConstraint -mo -skip y -skip z wrist_jnt forearmTwist02_jnt;

Set weight to 0.66 for 66% influence

Blender setup using drivers:

Add "Copy Rotation" constraint to twist bone

Target: Wrist bone, Space: Local

Mix Mode: Add, Influence: 0.5 (for middle twist bone)

CRITICAL: Only copy the twist axis (typically Y for Blender's bone orientation)

Unity setup:

Use Animation Rigging package

Add TwistCorrection component to twist bones

Set Source: Wrist transform

Set Twist Axis: appropriate axis

Set Weight: 0.33, 0.66 for distribution

Twist bone count recommendations:

Stylized/Mobile: 1 twist bone per limb segment

Realistic/PC: 2 twist bones per limb segment

Film quality: 3+ twist bones with muscle simulation

---

Name

Weight Painting Workflow

Description

Systematic approach to skin weighting that avoids common pitfalls

When

Binding mesh to skeleton

Example

Professional weight painting workflow:

STEP 1: Pre-binding checklist

- All transforms frozen on joints (Maya) / Applied on armature (Blender)

- Mesh at world origin with clean transforms

- Joint orientations validated

- Character in bind pose (T-pose or A-pose)

- Mesh topology clean (no n-gons in deformation areas)

STEP 2: Initial bind

Maya: Smooth Bind with Max Influences = 4 (mobile) or 8 (PC)

Blender: Parent with Automatic Weights, then Limit Total = 4

STEP 3: Problem areas to check FIRST

1. Shoulder/clavicle junction - check 90 degree arm raise

2. Hip/pelvis junction - check leg spread and kick

3. Spine twist - check 45 degree torso rotation

4. Wrist rotation - check 180 degree forearm twist

5. Knee/elbow at 90 degrees - check for volume loss

STEP 4: Weight painting rules

- Start with flood fill to establish base influence

- Use smooth brush at low intensity (0.1-0.2)

- ALWAYS work with Normalize on

- Never leave vertices with 0 total weight

- Check weights sum to 1.0 (normalization)

STEP 5: Iteration poses

Pose 1: Arms at 45 degrees (relaxed pose, most common)

Pose 2: Arms at 90 degrees (stress test shoulder)

Pose 3: Full arm twist (stress test forearm)

Pose 4: Deep knee bend (stress test hip/knee)

Pose 5: Spine twist + bend combo

Tools that save hours:

Maya: ngSkinTools (layer-based weights)

Blender: Mesh Data Transfer (copy weights from proxy mesh)

Both: Weight hammer to fix stray vertices

---

Name

Control Rig Architecture

Description

Build animator-friendly control rigs that are intuitive and non-destructive

When

Creating production character rigs

Example

Control rig hierarchy:

#

Character_GRP

|-- CONTROLS_GRP (visible to animators)

| |-- GLOBAL_CTRL (moves everything, world space)

| |-- COG_CTRL (center of gravity, under global)

| |-- BODY_CTRLS (spine, limbs, head)

| |-- FACE_CTRLS (facial controls)

| |-- SETTINGS (IK/FK switches, visibility)

|

|-- SKELETON_GRP (usually hidden)

| |-- BIND_SKELETON (what mesh is bound to)

| |-- DRIVER_SKELETON (controlled by rig)

|

|-- GEOMETRY_GRP (mesh, hidden in rig file)

|-- DO_NOT_TOUCH_GRP (constraints, nodes, systems)

Control shape conventions:

- Circles: Rotation controls (FK joints)

- Cubes/Boxes: Translation controls (IK targets)

- Arrows: Directional (foot roll, pole vectors)

- Diamonds: Attribute controls (blend, switches)

- Cross/Plus: Global or COG

Color coding (standard):

- Yellow: Center/spine controls

- Blue: Left side (L_)

- Red: Right side (R_)

- Green: Secondary/tweaks

- Purple: IK handles

- Cyan: FK controls

Control placement rules:

1. Controls should be where animators expect them

2. IK controls at the END of chains (wrist, ankle)

3. FK controls at EACH joint in chain

4. Pole vectors visible and snappable (knee, elbow)

5. All controls should have predictable pivot points

Essential control features:

- Space switching (world/local/custom)

- IK/FK blending with matching

- Stretch on/off with volume preservation

- Bendy/ribbon controls for organic deformation

- Follow attributes (head follows body, hands follow)

---

Name

FK/IK System Implementation

Description

Build robust FK/IK systems with seamless switching and matching

When

Creating limb rigs that need both control methods

Example

FK vs IK decision guide:

#

USE FK FOR:

- Overlapping action (follow-through)

- Swinging motions (arms walking)

- Swimming, flying

- Loose/relaxed poses

- Direct mocap input

#

USE IK FOR:

- Planted contacts (feet on ground)

- Pushing/pulling (hands on objects)

- Climbing, hanging

- Precise endpoint control

- Maintaining contact during body movement

IK/FK Switch Architecture:

#

Three skeleton chains:

1. FK_chain - driven by FK controls

2. IK_chain - driven by IK solver

3. BIND_chain - constrained to blend between FK/IK

#

BIND_chain joints are parentConstrained to both:

parentConstraint -mo FK_arm BIND_arm;

parentConstraint -mo IK_arm BIND_arm;

#

IK_FK_Switch attribute (0=FK, 1=IK) drives constraint weights

FK to IK Matching (Maya):

def fk_to_ik_match():

1. Get FK chain world positions/rotations

2. Snap IK handle to FK wrist position

3. Calculate pole vector position from FK chain

4. Snap pole vector to calculated position

5. Switch to IK (set attribute to 1)

pass

IK to FK Matching (Maya):

def ik_to_fk_match():

1. Get BIND chain world rotations

2. Apply rotations to FK controls

3. Switch to FK (set attribute to 0)

pass

Pole vector placement:

Position should be on the plane defined by shoulder-elbow-wrist

Distance: ~1.5x the length of the upper arm segment

Direction: Perpendicular to limb, toward natural bend

---

Name

Facial Rigging Strategy

Description

Choose and implement the right facial deformation system

When

Creating character facial rigs

Example

Facial Deformation Methods Comparison:

#

BLEND SHAPES (Morph Targets):

Pros:

- Precise artist control

- Perfect for stylized characters

- Easy to art direct

- No weight painting issues

Cons:

- Memory heavy (full mesh per shape)

- Hard to combine dynamically

- No procedural adjustment

- Lots of shapes needed (50-100+)

#

JOINT-BASED:

Pros:

- Light on memory

- Good for mobile/performance

- Easy to retarget

- Works with engine systems

Cons:

- Hard to get subtle deformation

- Weight painting face is tedious

- Limited expression range

#

HYBRID (Recommended for games):

- Bones for broad movement (jaw, brows, cheeks)

- Blend shapes for specific expressions

- Corrective shapes for problem poses

Essential facial shapes (FACS-based):

Brows: Inner raise, outer raise, lower, squeeze

Eyes: Upper lid raise/lower, lower lid raise, squint, wide

Nose: Wrinkle, flare, sneer

Mouth: Open, wide, narrow, pucker, funnel, smile, frown

Jaw: Open, left, right, forward

Cheeks: Puff, suck, raise

#

Typical counts:

Mobile game: 15-25 shapes

PC game: 40-60 shapes

AAA/Film: 100+ shapes with correctives

Jaw setup (hybrid approach):

1. Jaw bone handles open/close rotation

2. Blend shape handles lip seal (keeps lips together)

3. Driven key: JawRotation drives LipSeal shape 0-1

4. Secondary bones for lips can layer on top

Eye setup considerations:

- Eyelids should follow eyeball rotation

- Upper lid moves more than lower (70/30 split)

- Blink shape should work with any eye direction

- Cornea bulge blend shape for realistic eyes

---

Name

Corrective Blend Shapes

Description

Use pose-space deformation to fix problem areas that weights can't solve

When

Dealing with volume loss, interpenetration, or complex deformation

Example

Corrective shapes fix deformation at specific poses

They activate automatically based on joint rotations

#

Common corrective targets:

- Shoulder at 90 degrees (deltoid collapse)

- Elbow at 90+ degrees (bicep/tricep)

- Hip at 90 degrees (glute flatten)

- Knee at 90+ degrees (quad/calf compression)

- Wrist flexion/extension (tendon visibility)

Maya workflow with Pose Space Deformation (PSD):

1. Pose the joint to the problem position (e.g., shoulder 90)

2. Duplicate the deformed mesh

3. Sculpt the fix on the duplicate

4. Create blend shape from sculpted to original

5. Connect shape weight to joint rotation via driven key

Example driven key setup:

Shoulder rotation 0 degrees -> corrective shape 0.0

Shoulder rotation 45 degrees -> corrective shape 0.5

Shoulder rotation 90 degrees -> corrective shape 1.0

Use smooth interpolation (spline tangents)

Blender workflow with Shape Keys:

1. Create shape key from basis at problem pose

2. Apply armature modifier to see deformation

3. Sculpt corrections on the shape key

4. Add driver: Shape Key Value driven by bone rotation

5. Use scripted expression for smooth falloff

Extraction workflow (cleaner method):

1. Pose to problem position

2. Duplicate mesh

3. Remove skinning from duplicate

4. Sculpt fixes with clean topology reference

5. Create blend shape

6. Invert the deformation so it corrects at pose

Performance note:

Each corrective shape = mesh data in memory

Limit to 10-20 correctives per character for real-time

Use helper bones where possible instead

---

Name

Spine Deformation System

Description

Create spine rigs that bend naturally without breaking

When

Rigging humanoid or creature spines

Example

Spine hierarchy (humanoid):

#

Pelvis (root of spine, child of COG)

|-- Spine01 (lower back)

| |-- Spine02 (mid back)

| |-- Spine03 (upper back)

| |-- Chest (ribcage)

| |-- Neck01

| |-- Neck02

| |-- Head

#

Minimum spine joints: 3 (mobile)

Recommended: 4-5 (good balance)

High detail: 6+ (film/cutscene)

FK spine with ribbon/spline IK overlay:

1. FK controls at each spine joint (direct rotation)

2. IK spline curve through spine for smooth arcs

3. Blend between FK and spline IK per joint

Breathing setup:

- Scale Spine02/Spine03 slightly on breath attribute

- Scale should be Y-axis (vertical expansion)

- Subtle: 1.0 to 1.02 scale range

- Drive with sine wave for idle breathing

Twist distribution:

- Pelvis rotation should NOT twist spine

- Chest twist should distribute to Spine02/03

- Use aim constraints or twist extractors

Common spine problems and fixes:

#

Problem: Spine joints collapse on side bend

Fix: Add volume preservation via scale compensation

or corrective shapes at extreme bends

#

Problem: Shoulders move with spine twist

Fix: Counter-rotate clavicles or add shoulder space

#

Problem: Belly/chest interpenetration on bend

Fix: Lattice deformer or corrective shapes

#

Problem: Hip bone twists unnaturally

Fix: Separate pelvis rotation from spine chain

---

Name

Root Motion vs In-Place Animation

Description

Understand and implement proper root motion systems for game engines

When

Setting up character animation for gameplay

Example

Root Motion: Character movement baked into animation

In-Place: Animation plays in place, code handles movement

#

ROOT MOTION - Use when:

- Animation timing MUST match movement (footsteps)

- Complex locomotion (climbing, vaulting)

- Physics interactions (getting hit, stumbling)

- Cutscenes and mocap data

#

IN-PLACE - Use when:

- Gameplay needs responsive controls

- Speed varies dynamically

- Network sync is critical (competitive games)

- Procedural movement (following splines)

Root bone setup:

#

Required hierarchy:

Root (at world origin, this is your root motion bone)

|-- Pelvis (or Hips - the actual hip joint)

|-- Spine...

|-- L_Leg...

|-- R_Leg...

#

Root bone rules:

1. MUST be at world origin in bind pose (0,0,0)

2. Should have NO rotation in bind pose

3. Sits on the ground plane (Y=0) typically

4. Animation moves this bone for root motion

Unity root motion setup:

- Animator > Apply Root Motion = true

- Avatar must have correct Root Node assigned

- Call animator.deltaPosition in script for custom handling

Unreal root motion setup:

- Animation asset > Enable Root Motion = true

- Root Motion Mode = Root Motion from Everything

- Character Movement > Use Controller Desired Rotation

Extracting root motion in Maya:

1. Bake animation to root joint

2. Delete Y rotation if keeping feet on ground

3. Verify root doesn't go through ground plane

4. Export with "Bake Animation" enabled

Common root motion bugs:

- Character sliding (root motion not applied)

- Character teleporting (root in wrong location)

- Feet sliding (animation/movement speed mismatch)

- Rotation snapping (root rotation not smooth)

---

Name

Animation Retargeting Setup

Description

Create rigs that retarget animation cleanly to different proportions

When

Building characters that share animation sets or use mocap

Example

Retargeting requirements:

#

1. Consistent naming convention across all characters

- "Spine", "Spine1", "Spine2" not "Back", "Torso", "Chest"

- "LeftArm", "LeftForeArm" not "L_Arm", "L_Elbow"

#

2. Identical hierarchy structure

- Same joint count in chains

- Same parent-child relationships

- Same joint order

#

3. Matching joint orientations

- All characters X-axis down bone

- All characters Y-axis same direction

- This is the #1 retargeting failure cause

#

4. Similar bind pose

- A-pose or T-pose

- Consistent across characters

- Finger spread matters!

Unity Humanoid retargeting:

1. Set Rig type to "Humanoid"

2. Configure Avatar - map bones to Unity's humanoid

3. Required bones: Hips, Spine, Head, Arms, Legs

4. Optional: Fingers, toes, extra spine joints

#

Muscle limits (must configure):

- Shoulder range of motion

- Spine twist limits

- Neck limits

These prevent hyperextension on retarget

Unreal retargeting:

1. Create IK Rig for source skeleton

2. Create IK Rig for target skeleton

3. Create IK Retargeter asset

4. Map chains: Spine, Arms, Legs, Head

5. Adjust bone mapping for mismatches

Proportion adjustment strategies:

- Long arms → reduce arm FK influence or scale keys

- Short legs → foot IK with ground contact

- Different spine length → interpolate extra joints

#

What doesn't retarget well:

- Facial animation (use blend shapes directly)

- Finger animation (too proportion-sensitive)

- Props and contacts (need manual adjustment)

- Clothing/hair simulation (recalculate)

---

Name

Additive Animation Layers

Description

Implement layered animation systems for procedural and blended effects

When

Adding breathing, hit reactions, or procedural motion to base animations

Example

Additive animations add ON TOP of base animation

Base pose + Additive delta = Final pose

#

Common additive uses:

- Breathing (chest expansion)

- Look-at/head tracking

- Weapon recoil

- Damage reactions (hit flinches)

- Tiredness/fatigue overlay

- Emotional states

Creating additive animations:

#

Method 1: Reference pose subtraction

1. Create "Reference Pose" (usually T-pose or idle)

2. Create full animation (e.g., breathing idle)

3. Engine subtracts reference from animation

4. Result: Only the DIFFERENCE is stored

#

Method 2: Artist creates deltas directly

1. Start from bind pose (all zeroed)

2. Animate ONLY what should change

3. Mark as additive in engine

Unity additive setup:

1. Animation clip > Additive Reference Pose = true

2. Create Animator layer with Blending = Additive

3. Set layer weight (0-1) for intensity

4. Avatar Mask to limit affected bones

Unreal additive setup:

1. AnimSequence > Additive Settings > Additive Anim Type

2. Choose Mesh Space or Local Space additive

3. Set Base Pose Type (usually Reference Pose)

4. Use Layered Blend Per Bone in AnimGraph

Avatar Masks (critical for additives):

- Upper body mask for weapon handling

- Spine-only mask for breathing

- Head mask for look-at

Without masks, additives affect entire body

Common additive problems:

- Joints hyperextending (clamp rotation in blend)

- Additive + additive compounding (use maximum, not sum)

- Wrong reference pose (causes drift)

- Mesh space vs local space confusion

Anti-Patterns

---

Name

Non-zeroed Transforms

Description

Binding mesh to skeleton without freezing transforms

Why

Export will bake in offsets. Different DCCs interpret transforms differently. FBX will have "ghost" transforms. Animations will be offset.

Instead

Always Freeze Transforms (Maya) or Apply All Transforms (Blender) on both skeleton and mesh before binding. The bind pose should show all zeros in channel box.

---

Name

Binding in Wrong Pose

Description

Binding mesh when character is in animation pose instead of bind pose

Why

Weight painting assumes bind pose. Deformation will be wrong at rest. Can't share animation with other characters. Export breaks.

Instead

Always return to T-pose or A-pose before binding. Create a "bind pose" button/script that resets skeleton. Verify pose before every bind.

---

Name

Single Influence Joints

Description

Joints that only one vertex is weighted to, or very low influence

Why

Single vertices create hard edges in deformation. Low influences get culled on export. Creates popping artifacts.

Instead

Ensure minimum 3-4 vertices per joint influence. Use weight hammer to smooth isolated weights. Remove joints that don't contribute.

---

Name

Weight Islands

Description

Groups of vertices with weights disconnected from their neighbors

Why

Creates tears in mesh during deformation. Often invisible until animation plays. Very hard to debug.

Instead

Use "Select Influenced" to visualize per-joint weights. Smooth weights at boundaries. Use topology-aware weight transfer.

---

Name

Joint Limits in DCC

Description

Relying on joint limits set in Maya/Blender for runtime

Why

Most game engines ignore DCC joint limits completely. Maya IK joint limits export but don't constrain. Behavior differs between DCCs.

Instead

Implement limits in engine (Unity Constraints, Unreal Control Rig). Or use post-process in animation system. Never rely on DCC limits for runtime.

---

Name

Excessive Bone Count

Description

Creating detailed skeleton without considering target platform

Why

Mobile GPUs have hard bone limits (often 75 per draw call). Each bone costs CPU for transform updates. Skinning cost scales with bone count.

Instead

Mobile characters 30-50 bones. PC characters 75-120 bones. Split mesh by bone count for LOD. Use bone LOD systems.

---

Name

Floating Root Bone

Description

Root bone not at world origin or floating in space

Why

Root motion calculations assume origin. Retargeting breaks with offset roots. Export may compound transforms wrong.

Instead

Root bone at (0,0,0) with no rotation. Place at ground level. Only move root for root motion data.

---

Name

Inconsistent Joint Orientations

Description

Joint X-axis pointing random directions, orientations not mirrored properly

Why

Animation retargeting fails. Mirror animation fails. IK solving becomes unpredictable. Rotation interpolation glitches.

Instead

X-axis always aims down bone. Y-axis consistent (pick forward or up, stick with it). Mirror orientations properly for symmetry.

---

Name

Skinning Before Rig Completion

Description

Weight painting before the skeleton hierarchy is finalized

Why

Adding/removing joints invalidates weight data. Reparenting joints changes weight behavior. Multiple rebind cycles waste days.

Instead

Complete skeleton hierarchy first. Add ALL helper and twist bones. Test full range of motion with proxy geo. THEN bind final mesh.

---

Name

Over-relying on Corrective Shapes

Description

Using corrective blend shapes for problems that proper weights would solve

Why

Correctives cost memory and performance. Hard to maintain across LODs. Don't retarget. Compound complexity.

Instead

Fix weight painting first. Add helper bones second. Use correctives only for impossible deformation (shoulder at 180 degrees).

Rigging Animation - Sharp Edges

Rig Fbx Bind Pose Vs Rest Pose

Id

rig-fbx-bind-pose-vs-rest-pose

Summary

FBX exports bind pose and rest pose differently, causing skeleton offset

Severity

critical

Situation

Character rig works in Maya/Blender but skeleton is offset or scaled wrong in Unity/Unreal

Why

FBX has two pose concepts that DCCs handle differently:

• Bind Pose: The pose mesh was skinned to (stored in skin cluster)
• Rest Pose: The pose skeleton returns to when no animation applied

Maya's FBX exporter uses bind pose for skeleton. Blender's FBX exporter can use rest pose or current pose. If these don't match, engine imports with offsets. Unity especially struggles when bind != rest.

Solution

Before export: 1. Go to bind pose (Maya: Skin > Go To Bind Pose) 2. Freeze all joint transforms (Maya: Modify > Freeze Transformations) 3. In Blender: Apply armature transforms, ensure rest pose = bind pose 4. Export settings: Bake Animation, use scene units 5. Unity: Check "Bake Axis Conversion" in import settings

Validation:

• Joint positions should be identical in DCC and engine
• Skeleton should have no offset from mesh in T-pose
• No unexpected scaling on root or any joints

Symptoms

• Mesh floats away from skeleton in engine
• Character is scaled wrong
• Skeleton rotated 90 degrees
• Animation plays correctly but bind pose is offset

Detection Pattern

bind\spose|rest\spose|go\sto\sbind

Version Range

all

Rig Weight Normalization Culling

Id

rig-weight-normalization-culling

Summary

Export silently removes low-weight bone influences causing mesh tears

Severity

critical

Situation

Mesh tears or spikes appear in engine that weren't visible in DCC

Why

FBX export and game engines cull bone influences below thresholds:

• Weights below ~0.01 often removed entirely
• "Max bones per vertex" setting (usually 4) drops lowest weights
• Remaining weights get renormalized to sum to 1.0

If vertex had weights: BoneA=0.5, BoneB=0.49, BoneC=0.01 After cull: BoneA=0.505, BoneB=0.495 The 0.01 on BoneC might have been important for smooth falloff.

Solution

Before binding:

• Set Maya Smooth Bind to "Max Influences: 4" from start
• Blender: Limit Total vertex group after auto-weights

Before export:

• Maya: Prune Small Weights (0.01 threshold)
• Blender: Weights > Limit Total, then Clean (limit 0.01)

Problem vertices:

• Find vertices with many tiny influences
• Redistribute weight to main influences
• Never leave vertices with only 0.01 influence on any bone

Symptoms

• Mesh spikes or tears during animation
• Vertices "stick" to wrong bone
• Smooth areas in DCC are sharp in engine
• Export warnings about weight normalization

Detection Pattern

prune.weight|normalize|influence.limit|max.*influence

Version Range

all

Rig Joint Limit Export Ignore

Id

rig-joint-limit-export-ignore

Summary

Joint rotation limits set in DCC are ignored by game engines

Severity

high

Situation

IK solver over-rotates joints in engine despite limits set in Maya/Blender

Why

Maya/Blender joint limits are:

• Only for DCC IK solvers
• Stored in proprietary format
• NOT part of FBX specification

Game engines implement their own IK:

• Unity: Animation Rigging package has own limits
• Unreal: Control Rig has own constraint system
• Neither reads DCC joint limits from FBX

Solution

Unity implementation:

• Use Animation Rigging package
• Add "Two Bone IK Constraint" component
• Configure Hint (pole vector) and limits manually
• Or use "Damped Transform" for soft limits

Unreal implementation:

• Use Control Rig blueprint
• Add "Limit" nodes for rotation
• Set up per-axis min/max
• Use "Clamp" nodes for hard stops

Export from DCC:

• Document joint limits in text file
• Create screenshot reference of limit values
• Or build limits into animation (never exceed in source)

Symptoms

• Knee bends backward
• Elbow hyperextends
• IK works in DCC but breaks in engine
• Joints flip at extreme poses

Detection Pattern

joint.limit|rotation.limit|clamp.*rotation

Version Range

all

Rig Mobile Bone Count Limit

Id

rig-mobile-bone-count-limit

Summary

Mobile GPU skinning has hard limit around 75 bones per mesh

Severity

high

Situation

Character renders corrupted, flickers, or shows wrong pose on mobile devices

Why

Mobile GPU shader uniform limits:

• ~75-128 mat4 uniforms typical (bones use 3-4 vec4 each)
• ES 3.0 guarantees 256 vec4 (64-85 bones)
• Some devices much lower (older Android)

When exceeded:

• Some bones get garbage matrices
• Mesh deforms wildly
• May only happen on specific devices
• Often no error, just visual corruption

Solution

Design for limits:

• Mobile characters: 30-50 bones max
• Split mesh by bone region (body/face separate draw calls)
• Use bone LOD (reduce bones at distance)

Unity setup:

• Quality Settings > Blend Weights = 2 Bones (mobile)
• Check Skin Mesh Renderer bone count in editor
• Profile on target device

Unreal setup:

• Project Settings > Rendering > Max Bones Per Section
• Use Skeletal Mesh LOD with bone reduction
• Check "Bone Count" in Skeletal Mesh editor

Fallback:

• Bake animation to fewer bones procedurally
• Use simpler rig for mobile vs PC

Symptoms

• Character deforms wildly on mobile
• Works on high-end devices, breaks on low-end
• Mesh appears inside-out or scrambled
• Only some body parts render correctly

Detection Pattern

bone.count|mobile.limit|uniform.*limit

Version Range

all

Rig Root Bone Placement

Id

rig-root-bone-placement

Summary

Root bone not at world origin causes root motion and retargeting failures

Severity

high

Situation

Root motion doesn't work, character drifts, or retargeting produces offset

Why

Root motion calculation assumes:

• Root bone at (0, 0, 0) in bind pose
• Root bone has no rotation in bind pose
• Movement delta calculated from origin

If root is offset:

• Delta calculation includes offset
• Character may slide or teleport
• Rotation origin is wrong

For retargeting:

• Source and target root must match
• Any offset compounds across skeleton

Solution

Skeleton setup:

Correct hierarchy:

Root (0,0,0) - no rotation |-- Pelvis/Hips (actual hip position) |-- Spine... |-- Legs...

Root should be:

• At world origin
• On ground plane (Y=0 typically)
• Aimed down world +Z or +Y (project convention)
• No rotation applied

Before export:

• Freeze transforms on root
• Verify world space position is 0,0,0
• Animation only moves root for root motion data

Symptoms

• Root motion character slides
• Character teleports when animation plays
• Retargeted animation has offset
• Character not standing on ground in engine

Detection Pattern

root.motion|root.bone|origin|world.*origin

Version Range

all

Rig Candy Wrapper Forearm

Id

rig-candy-wrapper-forearm

Summary

Forearm twists cause mesh collapse without twist bones

Severity

high

Situation

Wrist rotation causes ugly pinching/twisting in forearm mesh

Why

Single forearm joint = all twist at one point Mesh vertices must travel maximum distance Creates characteristic "candy wrapper" collapse

Real forearm:

• Radius and ulna bones cross each other
• Twist distributes along forearm length
• Muscle volume shifts

Without twist bones:

• 180 degree twist = 180 degrees at single joint
• Mesh collapses to minimum diameter
• Looks like twisted candy wrapper

Solution

Add twist bones between elbow and wrist:

Minimum: 1 twist bone

Elbow |-- ForearmTwist (50% from elbow to wrist) |-- Wrist

Recommended: 2 twist bones

Elbow |-- ForearmTwist01 (33% position, 33% twist) |-- ForearmTwist02 (66% position, 66% twist) |-- Wrist (100% twist)

Twist distribution:

• Maya: Orient constraint to wrist, skip Y/Z
• Blender: Copy Rotation constraint, single axis
• Set weight/influence to match position percentage

Weight painting:

• Twist bones get forearm mesh weights
• Gradient from elbow to wrist
• No sharp transitions

Symptoms

• Forearm pinches on wrist rotation
• Mesh volume collapses
• Geometry crosses itself
• Textures stretch unnaturally

Detection Pattern

twist.bone|forearm.twist|candy.wrapper|roll.bone

Version Range

all

Rig Shoulder Deformation Complexity

Id

rig-shoulder-deformation-complexity

Summary

Shoulder joint requires special handling for realistic deformation

Severity

high

Situation

Shoulder deforms poorly when arm raises, deltoid collapses, armpit stretches

Why

Shoulder is anatomically complex:

• Clavicle rotates and translates
• Scapula slides across back
• Deltoid wraps around joint
• Different behavior for front/side/back raise

Single shoulder joint can't capture this Even good weights fail at extreme poses

Solution

Joint hierarchy: Spine (chest level) |-- Clavicle (rotates up on arm raise) |-- Shoulder (main arm rotation) |-- ShoulderHelper (auto-rotates 30% of shoulder) |-- UpperArm...

Helper bone setup:

• Position between shoulder and bicep
• Orient constraint to shoulder, 0.3 weight
• Smooths extreme rotations

Clavicle behavior:

• Arm at side: clavicle rotated down/back
• Arm at 90: clavicle rotated up ~15-20 degrees
• Arm at 180: clavicle rotated up ~30+ degrees
• Use SDK (Set Driven Key) for automatic

Corrective shapes needed:

• Arm at 90 front: deltoid volume
• Arm at 90 side: armpit close
• Arm at 90 back: trap engagement

Symptoms

• Deltoid muscle flattens when arm raises
• Armpit has holes or stretching
• Shoulder "pops" at certain angles
• Can't get smooth rotation through full range

Detection Pattern

shoulder|clavicle|deltoid|armpit

Version Range

all

Rig Humanoid Vs Generic Unity

Id

rig-humanoid-vs-generic-unity

Summary

Unity Humanoid rig type alters animation data and may break custom rigs

Severity

medium

Situation

Custom rig animations play wrong in Unity when using Humanoid avatar

Why

Unity Humanoid rig system:

• Remaps bones to Unity's internal skeleton
• Applies muscle limits
• Normalizes bone orientations
• Loses custom bone data (props, twist bones)

Issues with Humanoid:

• Extra bones ignored or removed
• Custom orientations overwritten
• Animation data converted (lossy)
• IK retargeting may fight custom IK

Solution

Use Humanoid when:

• Sharing animations between characters
• Using Unity's built-in IK
• Simple bipedal characters
• Using humanoid animation assets

Use Generic when:

• Custom skeleton with extra bones
• Precise animation needed
• Non-humanoid characters
• Performance-critical (no retargeting overhead)

Hybrid approach:

• Main skeleton as Humanoid for retargeting
• Extra bones (twist, helpers) as Generic layer
• Use Animation Rigging for procedural additions

If using Humanoid:

• Configure Avatar carefully
• Set muscle limits to match rig
• Verify bone mapping in debug view
• Test animation after import

Symptoms

• Animations look "floaty" or different from DCC
• Custom bones don't animate
• IK behaves unexpectedly
• Rotation values different than keyframed

Detection Pattern

humanoid|avatar|generic.*rig|mecanim

Version Range

Unity

Rig Fbx Axis Conversion

Id

rig-fbx-axis-conversion

Summary

DCC to engine axis conversion causes 90-degree rotation on export

Severity

medium

Situation

Character is rotated 90 degrees or has swapped axes in engine

Why

Different coordinate systems:

• Maya: Y-up, right-handed
• Blender: Z-up, right-handed (by default)
• Unity: Y-up, left-handed
• Unreal: Z-up, left-handed

FBX can convert, but results vary:

• Some exporters add 90 rotation to root
• Some flip axes incorrectly
• Animation may or may not convert

Solution

Maya to Unity:

• FBX export: Axis Conversion = Off
• Unity import: Bake Axis Conversion = On
• Character faces +Z in Maya = +Z in Unity

Blender to Unity:

• FBX export: Apply Transform, Forward -Z, Up Y
• Unity import: Bake Axis Conversion = On
• Or: Model facing -Y in Blender = +Z in Unity

Blender to Unreal:

• FBX export: Apply Transform
• Forward X or -Y (test which works)
• Unreal: Force Front XAxis in import

General rule:

• Pick convention and document it
• Create test cube with labeled faces
• Export cube first to verify orientation
• Same settings for skeleton and mesh

Symptoms

• Character facing wrong direction
• Character lying down instead of standing
• Animations rotated 90 degrees
• Left/right swapped

Detection Pattern

axis.conversion|y.up|z.up|rotation.90

Version Range

all

Rig Blend Shape Vertex Order

Id

rig-blend-shape-vertex-order

Summary

Blend shapes break if mesh vertex order changes

Severity

medium

Situation

Blend shapes cause wild mesh deformation after mesh edits

Why

Blend shapes store per-vertex deltas by index Vertex indices must match between base and target

Operations that change vertex order:

• Adding/removing vertices
• Boolean operations
• Some modifiers (mirror, subdivision)
• Merging vertices
• Import/export (sometimes)

Result:

• Delta applied to wrong vertex
• Mesh explodes or deforms randomly
• Some vertices affected, others not

Solution

Workflow protection:

• Lock base mesh after blend shape creation
• Only sculpt on blend shape copies
• Never modify base topology

If you must edit base:

• Export all blend shapes first
• Modify base mesh
• Transfer blend shapes using UV space
• Verify every shape manually

Tools for transfer:

• Maya: BlendShape Editor > Transfer
• Blender: Join as Shapes (from mesh)
• Third-party: Wrap3, R3DS Wrap

Detection:

• Test blend shapes at 100% after any mesh change
• Look for asymmetry in symmetric shapes
• Check vertex count matches

Symptoms

• Blend shape causes mesh explosion
• Only part of mesh moves correctly
• Blend shape creates asymmetry
• Shapes worked before, broken after mesh edit

Detection Pattern

blend.shape|morph.target|vertex.*order

Version Range

all

Rig Animation Compression Artifacts

Id

rig-animation-compression-artifacts

Summary

Game engine animation compression causes visible popping or drift

Severity

medium

Situation

Smooth animation in DCC has pops, jitters, or drift in engine

Why

Engines compress animation:

• Keyframe reduction (removes redundant keys)
• Curve simplification
• Quantization (reduced precision)
• Different interpolation methods

Small rotations affected most:

• Fingers, facial bones
• Subtle secondary motion
• Idle breathing

Accumulating error:

• Looping animations drift over time
• Root motion doesn't return to origin

Solution

Unity settings:

• Animation > Anim. Compression: Off (for quality)
• Or: Optimal with higher Error threshold
• Increase precision for facial/finger bones
• Check "Resample Curves" behavior

Unreal settings:

• Animation asset > Compression Settings
• Use "Automatic" and preview before ship
• Per-bone compression settings for critical bones
• Max Diff thresholds per bone

Animation authoring:

• Add keys on important frames (not just auto)
• Use linear tangents for mechanical motion
• Avoid very small rotation changes
• Test loop seams explicitly

Symptoms

• Animation has subtle pops
• Character slowly drifts from position
• Loop doesn't seamlessly connect
• Fingers jitter during animation

Detection Pattern

compression|keyframe.reduction|animation.quality

Version Range

all

Rig Scale In Skeleton

Id

rig-scale-in-skeleton

Summary

Non-uniform scale on skeleton joints breaks skinning and animation

Severity

high

Situation

Skeleton has scale values other than 1,1,1 causing export and animation issues

Why

Scale in skeleton hierarchy:

• Compounds down the chain
• Affects skinning unpredictably
• Different engines handle differently
• Animation scale keys problematic

Problems:

• Shear/skew when rotating scaled joints
• Skinning weights behave wrong
• Export may bake or lose scale
• Retargeting fails completely

Solution

Prevention:

• NEVER scale skeleton joints
• Model character at correct size initially
• Scale control curves instead of joints
• Use rig scale attribute on root control

Fixing scaled skeleton:

• Maya: Freeze all joint transforms
• Blender: Apply scale to armature
• Rebuild skeleton from scratch if needed

If intentional scale needed:

• Only use uniform scale (same X,Y,Z)
• Only on root or top of hierarchy
• Test full animation range
• Test export before investing more work

Squash/stretch alternative:

• Use constraints/expressions for stretch
• Scale along single axis only
• Apply scale to helper bone, not bind skeleton

Symptoms

• Mesh shears on rotation
• Skinning pulls in wrong direction
• Export has different proportions
• Animation data looks wrong in curves

Detection Pattern

scale|transform.scale|non.uniform

Version Range

all

Rig Ik Chain Orientation

Id

rig-ik-chain-orientation

Summary

IK solver fails or flips when joint orientations are inconsistent

Severity

high

Situation

IK solution flips, jitters, or finds wrong solution

Why

IK solvers use joint orientation to determine:

• Which way to bend (pole direction)
• Twist along bone
• Solution preference

Inconsistent orientations:

• Solver can't predict bend direction
• May flip 180 at certain angles
• Different solutions depending on start pose

Solution

Joint orientation rules for IK:

All joints in chain must have:

- Primary axis (X) pointing to child

- Secondary axis (Y) pointing toward bend

- Tertiary axis (Z) consistent twist

Arm IK:

• Shoulder/Elbow/Wrist X -> toward child
• Y -> forward (direction elbow bends)
• Pole vector placed behind elbow

Leg IK:

• Hip/Knee/Ankle X -> toward child
• Y -> forward (direction knee bends)
• Pole vector placed in front of knee

Validation in Maya:

• Select joint > Display Local Rotation Axes
• Verify X aims down chain
• Verify Y consistent in bend direction

Pole vector placement:

• On the plane of the bent chain
• Perpendicular to straight chain
• Distance: 1-2x limb length for stability

Symptoms

• IK flips at certain angles
• IK jitters when near straight
• Pole vector seems to have no effect
• IK finds unexpected solutions

Detection Pattern

ik.flip|pole.vector|joint.*orient

Version Range

all

Rigging Animation - Validations

Hardcoded Joint Names

Id

rig-maya-hardcoded-joint-names

Severity

warning

Type

regex

Pattern

• cmds\.joint\([^)]name\s=\s["'](?!.{)[^"']+["']
• pm\.joint\([^)]name\s=\s["'](?!.{)[^"']+["']

Message

Hardcoded joint names make rigs inflexible. Use naming convention variables or template strings.

Fix Action

Create naming convention constants: SIDE_PREFIX, JOINT_SUFFIX, etc. Use f-strings or format().

Applies To

• *.py
• *.mel

Bind Skin Without Max Influences

Id

rig-maya-bind-without-max-influences

Severity

warning

Type

regex

Pattern

• skinCluster\([^)](?!.maximumInfluences)[^)]*\)
• bindSkin\([^)](?!.tsb)[^)]*\)

Message

Binding without max influences limit may exceed engine bone limits. Mobile: 4, PC: 8 max.

Fix Action

Add maximumInfluences=4 parameter for mobile, maximumInfluences=8 for PC targets.

Applies To

• *.py
• *.mel

Joint Orient Check Missing

Id

rig-maya-joint-orient-not-zeroed

Severity

warning

Type

regex

Pattern

• makeIdentity\([^)]apply\s=\s(?:True|1)[^)]\)(?![\s\S]*?jointOrient)

Message

Freezing transforms without checking joint orient may cause animation issues.

Fix Action

After freezeTransformations, verify jointOrient values are as expected for the rig.

Applies To

• *.py
• *.mel

Parent Constraint Without Maintain Offset

Id

rig-maya-parent-constraint-no-maintain-offset

Severity

warning

Type

regex

Pattern

• parentConstraint\([^)](?!.mo=|.maintainOffset)[^)]\)

Message

Parent constraint without maintainOffset can cause unexpected snapping.

Fix Action

Add mo=True or maintainOffset=True to preserve relative positioning.

Applies To

• *.py
• *.mel

IK Handle Without Solver Specification

Id

rig-maya-ikhandle-no-solver-type

Severity

warning

Type

regex

Pattern

• ikHandle\([^)](?!.solver|.sol)[^)]\)

Message

IK handle without explicit solver type may default unexpectedly (SC vs RP).

Fix Action

Specify solver='ikRPsolver' for limbs or solver='ikSCsolver' for simple chains.

Applies To

• *.py
• *.mel

Bone Roll Not Explicitly Set

Id

rig-blender-bone-roll-not-set

Severity

warning

Type

regex

Pattern

• edit_bones\.new\([^)]\)(?![\s\S]{0,100}\.roll\s=)

Message

Bone created without setting roll. Inconsistent rolls cause IK and retargeting issues.

Fix Action

Set bone.roll explicitly after creation. Use bpy.ops.armature.calculate_roll() for consistency.

Applies To

• *.py

Bone Constraint Missing Subtarget

Id

rig-blender-constraint-no-subtarget

Severity

error

Type

regex

Pattern

• constraints\.new\([^)](?:'COPY_|'IK'|'DAMPED_TRACK')[^)]\)[\s\S]{0,200}(?!.*subtarget)

Message

Bone constraint without subtarget will likely fail. Target bone not specified.

Fix Action

Set constraint.subtarget = 'bone_name' after adding the constraint.

Applies To

• *.py

Using Only Automatic Weights

Id

rig-blender-auto-weights-only

Severity

warning

Type

regex

Pattern

• bpy\.ops\.object\.parent_set\([^)]type\s=\s*['"]ARMATURE_AUTO['"]

Message

Automatic weights alone often need cleanup. Add weight normalization and limit total.

Fix Action

Follow up with bpy.ops.object.vertex_group_limit_total(limit=4) and clean weights.

Applies To

• *.py

Armature Scale Not Applied

Id

rig-blender-armature-scale-not-applied

Severity

warning

Type

regex

Pattern

• bpy\.data\.armatures\.new\([^)]*\)(?![\s\S]{0,500}bpy\.ops\.object\.transform_apply)

Message

Armature created without applying transforms. Scale issues will cause export problems.

Fix Action

After armature creation, use bpy.ops.object.transform_apply(location=True, rotation=True, scale=True).

Applies To

• *.py

HumanBodyBones Magic String Usage

Id

rig-unity-animator-getbone-magic-string

Severity

warning

Type

regex

Pattern

• GetBoneTransform\([^)]*HumanBodyBones\.\w+

Message

Using HumanBodyBones directly. Consider caching bone transforms for performance.

Fix Action

Cache bone transforms in Awake() instead of calling GetBoneTransform every frame.

Applies To

• *.cs

Animation Rigging Without Weight Control

Id

rig-unity-animation-rigging-no-weight

Severity

warning

Type

regex

Pattern

• TwoBoneIKConstraint|MultiAimConstraint|DampedTransform

Message

Animation Rigging constraint detected. Ensure weight property is exposed for blending.

Fix Action

Add [Range(0,1)] public float constraintWeight and control via RigBuilder.layers.

Applies To

• *.cs

Root Motion Without Delta Check

Id

rig-unity-root-motion-direct-access

Severity

warning

Type

regex

Pattern

• animator\.rootPosition|animator\.rootRotation(?![\s\S]{0,50}delta)

Message

Accessing root position/rotation directly. Consider using deltaPosition/deltaRotation for movement.

Fix Action

Use animator.deltaPosition and animator.deltaRotation for frame-based root motion.

Applies To

• *.cs

Avatar Mask Without Null Check

Id

rig-unity-avatar-mask-null-check

Severity

warning

Type

regex

Pattern

• \.avatarMask\s=\s\w+(?![\s\S]{0,50}null)

Message

Setting avatar mask without null check. Missing masks cause layer to affect all bones.

Fix Action

Add null check: if (mask != null) layer.avatarMask = mask;

Applies To

• *.cs

IK Weight Not Animated

Id

rig-unity-ik-no-weight

Severity

warning

Type

regex

Pattern

• SetIKPositionWeight\([^,]+,\s1(?:\.0)?f?\s\)
• SetIKRotationWeight\([^,]+,\s1(?:\.0)?f?\s\)

Message

IK weight set to 1 without transition. This causes snapping. Lerp weights for smooth IK.

Fix Action

Lerp IK weight over time: ikWeight = Mathf.Lerp(ikWeight, targetWeight, Time.deltaTime * speed);

Applies To

• *.cs

Skeletal Mesh Without LOD Setup

Id

rig-unreal-skeletal-mesh-no-lod

Severity

warning

Type

regex

Pattern

• USkeletalMesh\*(?![\s\S]{0,200}LOD|GetNumLODs)

Message

Skeletal mesh referenced without LOD consideration. Performance issue on complex characters.

Fix Action

Implement LOD switching. Use GetNumLODs() and SetForcedLOD() for distance-based quality.

Applies To

• *.cpp
• *.h

Unsafe Animation Instance Cast

Id

rig-unreal-animation-instance-cast

Severity

warning

Type

regex

Pattern

• Cast<U\wAnimInstance>\s\([^)]*GetAnimInstance\(\)

Message

Direct cast of AnimInstance may return null. Check before using.

Fix Action

Use if (UMyAnimInstance* Anim = Cast<UMyAnimInstance>(Mesh->GetAnimInstance())) { ... }

Applies To

• *.cpp

Control Rig Element Without Weight

Id

rig-unreal-control-rig-no-weight

Severity

warning

Type

regex

Pattern

• FRigUnit_\w+(?![\s\S]{0,100}Weight)

Message

Control Rig unit detected. Ensure Weight parameter is exposed for blending.

Fix Action

Add UPROPERTY Weight float to rig unit and use for procedural blending.

Applies To

• *.cpp
• *.h

FBX Export Without Animation Bake

Id

rig-fbx-python-no-bake

Severity

warning

Type

regex

Pattern

• FBXExport[^;](?!.[Bb]ake)
• export_scene_fbx\([^)](?!.bake_anim)

Message

FBX export without baking may not include all animation data correctly.

Fix Action

Enable bake_anim=True in Blender, or 'Bake Animation' in Maya FBX export settings.

Applies To

• *.py
• *.mel

Magic Numbers for Bone Limits

Id

rig-script-magic-bone-numbers

Severity

warning

Type

regex

Pattern

• bone.(?:count|limit|max)\s[=<>]\s*(?:75|128|256|4|8)\b
• influence.(?:count|limit|max)\s[=<>]\s*[0-9]+

Message

Magic numbers for bone/influence limits. Define constants for platform targets.

Fix Action

Create constants: MOBILE_MAX_BONES = 75, PC_MAX_BONES = 128, MOBILE_INFLUENCES = 4

Applies To

• *.py
• *.cs
• *.cpp

Hardcoded Twist Percentages

Id

rig-script-twist-hardcoded-percentage

Severity

warning

Type

regex

Pattern

• twist.(?:weight|influence|factor)\s=\s*0\.[0-9]+

Message

Hardcoded twist bone percentages. Make configurable for different character proportions.

Fix Action

Create twist_distribution list or calculate based on bone chain position.

Applies To

• *.py
• *.cs
• *.cpp

Weight Assignment Without Normalization

Id

rig-script-weight-no-normalize

Severity

warning

Type

regex

Pattern

• setAttr.\.weightList|vertex_group.add\([^)]*\)(?![\s\S]{0,200}normaliz)

Message

Weight assignment without normalization step. Weights may not sum to 1.0.

Fix Action

After weight changes, call normalize weights function or verify total = 1.0 per vertex.

Applies To

• *.py
• *.mel

Joint Creation in Loop Without Hierarchy Check

Id

rig-script-joint-creation-loop

Severity

warning

Type

regex

Pattern

• for.*:[\s\S]{0,50}(?:joint\(|edit_bones\.new|AddBone)(?![\s\S]{0,100}parent)

Message

Creating joints in loop without explicit parent assignment. Hierarchy may be wrong.

Fix Action

Explicitly set parent joint/bone after creation in loop. Don't rely on selection.

Applies To

• *.py
• *.mel

IK Chain Length Not Validated

Id

rig-script-ik-chain-length

Severity

warning

Type

regex

Pattern

• ikHandle|TwoBoneIK|FABRIK(?![\s\S]{0,200}(?:chain.length|joint.count|bone.*count))

Message

IK chain created without validating joint count. Wrong chain length causes solve failures.

Fix Action

Validate chain has expected joint count before creating IK. Log warning if mismatch.

Applies To

• *.py
• *.cs
• *.cpp

Loop Animation Endpoint Mismatch Risk

Id

rig-animation-loop-endpoint

Severity

warning

Type

regex

Pattern

• loop.anim|cycl.anim|WrapMode\.Loop

Message

Looping animation detected. Verify first and last keyframes match for seamless loop.

Fix Action

Check that frame 0 and final frame have identical bone transforms. Use 'paste flipped' for walk cycles.

Applies To

• *.py
• *.cs
• *.cpp

Additive Animation Without Reference Pose

Id

rig-additive-no-reference

Severity

warning

Type

regex

Pattern

• additive|AdditiveReferencePose|AnimationType\.Additive

Message

Additive animation setup. Verify reference pose is correctly set or deltas will be wrong.

Fix Action

Set reference pose to T-pose or idle base. Test additive at 100% to verify delta looks correct.

Applies To

• *.py
• *.cs
• *.cpp
• *.asset

Root Motion Loop May Drift

Id

rig-root-motion-loop-drift

Severity

warning

Type

regex

Pattern

• root.motion.loop|EnableRootMotion.*true[\s\S]{0,200}loop

Message

Root motion with looping animation. Verify root returns to origin at loop point.

Fix Action

At final frame, root position delta should equal 0. Extract and verify root motion curve endpoint.

Applies To

• *.py
• *.cs
• *.cpp