Humanoid Rig Requirements for IK: Difference between revisions

From Resonite Wiki
m remove "download sample rig" link as it leads nowhere
Added more details on a common digitgrade leg solution with the location of the component required added.
 
(10 intermediate revisions by 7 users not shown)
Line 1: Line 1:
<!--T:1-->
When you [[Importing Assets|import]] a rigged model to try and turn it into an [[Avatar|avatar]], it can be confusing to know what's required and what's not for best results. This page exists to help you understand the requirements.
When you import a rigged model to try and turn it into an avatar. It can be confusing to know what's required and what's not for best results. This page exists to help you understand the requirements.


= Support Formats = <!--T:9-->
== Supported Formats ==
If you have a rigged model that's compatible with other VR Platforms such as VRChat etc, then it should work out of the box. Just try importing the avatar.  
If you have a rigged model that's compatible with other VR Platforms such as VRChat etc, then it should work out of the box. Just try importing the avatar.  


<!--T:10-->
As a reminder, we '''don't''' currently support the importing of <code>.unitypackage</code> / <code>.vrm</code> / <code>.asset</code> / <code>.mesh</code> / <code>.prefab</code> files.
As a reminder, we '''don't''' currently support the importing of <code>.unitypackage</code> / <code>.vrm</code> / <code>.asset</code> / <code>.mesh</code> / <code>.prefab</code> files.


<!--T:11-->
Supported '''Humanoid Avatar''' formats:
Supported '''Humanoid Avatar''' formats:
* FBX
* FBX
* GLTF
* GLTF
* Blender


= Overall Rig/Model Requirements = <!--T:12-->
== Overall Rig/Model Requirements ==


== General Guidance == <!--T:49-->
=== Definitions ===
3D Engines and Tools have many different ways to refer to the same thing. To aid in reading this guide, some terms are clarified below for what they mean in Resonite.
* Segment - A single bone within a Rig. For example if a Finger has 3 Bones, then it has 3 Segments
* [[IK]] - Inverse Kinematics. The system used to pose your Rig in Resonite
 
=== General Guidance ===
* Your model should be in an A-pose or T-Pose.
* Your model should be in an A-pose or T-Pose.
* The Orientation (forward facing direction) of your model should be along the positive Z axis.  
* The Orientation (forward facing direction) of your model should be along the positive Z axis.  
Line 22: Line 25:
*** Check the "Force T-pose" option in the advanced import settings. If hands are crossed, rotate 180 degrees along the Z (up-down) axis. If one hand is in front and the other hand is in back, rotate 90 degrees along the Z (up-down) axis.
*** Check the "Force T-pose" option in the advanced import settings. If hands are crossed, rotate 180 degrees along the Z (up-down) axis. If one hand is in front and the other hand is in back, rotate 90 degrees along the Z (up-down) axis.


== Ignoring Bones == <!--T:47-->
=== Ignoring Bones ===
Sometimes, you might want to ignore a bone in the IK process within Resonite. Luckily you can do this. Simply add <code><NoIK></code>('''case insensitive''') to the Bone's name '''anywhere within the bone's name'''. This bone will then not be considered for IK purposes. It's children will though. This is often useful for twist bones or clothing/hair bones that are being detected as skeletal/IK bones.
Sometimes, you might want to ignore a bone in the IK process within Resonite. Luckily you can do this. Simply add <code><NoIK></code>('''case insensitive''') to the Bone's name '''anywhere within the bone's name'''. This bone will then not be considered for IK purposes. It's children will though. This is often useful for twist bones or clothing/hair bones that are being detected as skeletal/IK bones.


<!--T:48-->
{| class="wikitable"
{| class="wikitable"
!Bone Name
!Bone Name
Line 64: Line 66:
|}
|}


= Bone Requirements = <!--T:13-->
== Bone Requirements ==
When you import a model, Resonite uses pattern matching and heuristics to figure out the layout of your Model's Bones. This means that bone names are largely case insensitive and can have additional data around the name. As an example "hips", "Hips", "HIPS" and "cheese_hips" should all be detected as the model's hip bone. The heuristics are also forgiving of spaces so "upper arm" and "upperarm" should also be flagged correctly as an "Upper Arm" bone.
When you import a model, Resonite uses pattern matching and heuristics to figure out the layout of your Model's Bones. This means that bone names are largely case insensitive and can have additional data around the name. As an example "hips", "Hips", "HIPS" and "cheese_hips" should all be detected as the model's hip bone. The heuristics are also forgiving of spaces so "upper arm" and "upperarm" should also be flagged correctly as an "Upper Arm" bone.


<!--T:14-->
This is quite good at picking up a variety of rigs but to help you can follow this format.  
This is quite good at picking up a variety of rigs but to help you can follow this format.  


<!--T:15-->
An extensive guide is presented below, with a key information for each segment of the body.  
An extensive guide is presented below, with a key information for each segment of the body.  


<!--T:16-->
If this is too much detail you can also skip to a [[#Overall Summary|summary]].
If this is too much detail you can also skip to a [[#Overall Summary|summary]].


== Central Spine/Hips == <!--T:17-->
=== Central Spine/Hips ===


<!--T:18-->
The root of the model's armature should be a single hips bone, that faces upwards, see the table below for valid names for it.
The root of the model's armature should be a single hips bone, that faces upwards, see the table below for valid names for it.
 
[[File:IK Rig Torso.png|alt=Blender viewport showing bones, going from bottom to top: Hips, Spine, Chest and Neck.|thumb|365x365px|Example hip/central spine layout]]
<!--T:19-->
[[File:HumanoidRigHips.png|thumb|200px|Example hip/central spine layout|alt=Blender viewport showing bones, going from bottom to top: Hips, Spine, Chest and Neck.]]
 
<!--T:20-->
Following the hips should be a chain that leads from the hips upwards: Hips -> Spine -> Chest -> Neck -> Head.
Following the hips should be a chain that leads from the hips upwards: Hips -> Spine -> Chest -> Neck -> Head.


<!--T:21-->
So in summary:
So in summary:
{| class="wikitable"
{| class="wikitable"
Line 121: Line 114:
|}
|}


=== Upper Chests === <!--T:53-->
==== Upper Chests ====
Many Avatars have an extra bone segments in the central spine, that's usually called "Upper Chest" or "Spine2".
Many Avatars have an extra bone segments in the central spine, that's usually called "Upper Chest" or "Spine2".
# Hips
# Hips
Line 130: Line 123:
# Head
# Head


<!--T:54-->
These are '''NOT required, but we still support these.''' In these cases the "middle" "Spine" bone will be ignored for the purposes of IK.
These are '''NOT required, but we still support these.''' In these cases the "middle" "Spine" bone will be ignored for the purposes of IK.


== Shoulders and Arms == <!--T:22-->
=== Shoulders and Arms ===
Two arms should be attached to the "Chest" bone from above, one for each side of the model. Use the letters "L" and "R" to indicate which side of the model the arm is on. These are also case insensitive so "l" and "r" are ok.
Two arms should be attached to the "Chest" bone from above, one for each side of the model. Use the letters "L" and "R" to indicate which side of the model the arm is on. These are also case insensitive so "l" and "r" are ok.


<!--T:23-->
The order should follow: Shoulder -> Upper Arm -> Lower Arm -> Hand. We'll cover fingers in another segment.
The order should follow: Shoulder -> Upper Arm -> Lower Arm -> Hand. We'll cover fingers in another segment.
 
[[File:IK Rig Arm.png|alt=Blender window showing a sample arm bone rig in A-pose.|thumb|228x228px|Example arm rig layout]]
<!--T:24-->
[[File:HumanoidRigArm.png|thumb|200px|Example arm rig layout|alt=Blender window showing a sample arm bone rig in A-pose.]]
 
<!--T:25-->
{| class="wikitable"
{| class="wikitable"
!Order
!Order
Line 165: Line 152:
|}
|}


== Hands == <!--T:26-->
=== Hands ===
 
[[File:IK Rig Hand.png|alt=blender window showing a sample hand bone rig with each individual fingers|thumb|230x230px|Example fingers rig layout]]
<!--T:27-->
[[File:HumanoidRigFingers.png|thumb|200px|Example fingers rig layout|alt=blender window showing a sample hand bone rig with each individual fingers]]
 
<!--T:28-->
Hands can appear quite complex but they don't need to be. '''Before we move onto bone names''' keep in mind the following:
Hands can appear quite complex but they don't need to be. '''Before we move onto bone names''' keep in mind the following:
* Fingers
* Fingers
Line 183: Line 166:
** We need an identifiable thumb.
** We need an identifiable thumb.


<!--T:29-->
Additionally, if your model has 5 fingers, we'll use geometric detection to figure out what your bones are called. This process looks at the rig and can figure out which finger is which.
Additionally, if your model has 5 fingers, we'll use geometric detection to figure out what your bones are called. This process looks at the rig and can figure out which finger is which.


<!--T:30-->
Even with these things in mind, you may want to setup the fingers manually. So as with other segments here are some comments on the names of the bones.
Even with these things in mind, you may want to setup the fingers manually. So as with other segments here are some comments on the names of the bones.


<!--T:31-->
For each finger: <code><fingername>1 -> <fingername>2 -> <fingername>3 -> <fingername>4</code>
For each finger: <code><fingername>1 -> <fingername>2 -> <fingername>3 -> <fingername>4</code>


<!--T:32-->
Where the finger names are:
Where the finger names are:
* Thumb
* Thumb
Line 200: Line 179:
* Pinky
* Pinky


<!--T:33-->
Or explained in a table:
Or explained in a table:


<!--T:34-->
{| class="wikitable"
{| class="wikitable"
!Finger Number
!Finger Number
Line 236: Line 213:
|}
|}


=== Finger Identification === <!--T:45-->
==== Finger Identification ====
Resonite uses the following code to try and find what your fingers are:
Resonite uses the following code to try and find what your fingers are:
<pre>
<pre>
Line 252: Line 229:
         return FingerType.Pinky;
         return FingerType.Pinky;


    <!--T:46-->
return null;
return null;
}
}
</pre>
</pre>
As you can see its quite flexible and forgiving.
As you can see it's quite flexible and forgiving.


== Legs == <!--T:35-->
=== Legs ===
Legs are simple compared to everything else. Each leg should be connected to the Hip bone. Use the letters "L" and "R" to indicate which side of the model the arm is on. These are also case insensitive so "l" and "r" are ok.
Legs are simple compared to everything else. Each leg should be connected to the Hip bone. Use the letters "L" and "R" to indicate which side of the model the arm is on. These are also case insensitive so "l" and "r" are ok.
 
[[File:IK Rig Leg.png|alt=Blender window showing a sample leg bones layout from the side|thumb|441x441px|Example leg rig layout]]
<!--T:36-->
[[File:HumanoidRigLeg.png|thumb|200px|Example leg rig layout|alt=Blender window showing a sample leg bones layout from the side]]
 
<!--T:37-->
{| class="wikitable"
{| class="wikitable"
!Order
!Order
Line 287: Line 259:
|}
|}


=== Digitigrade Legs === <!--T:55-->
==== Digitigrade Legs ====
Resonite '''does not''' support Digitigrade legs natively. Many community members have created methods to support them though, such as by using the CopyGlobalTransform components to copy the movements of a dummy plantigrade leg onto non-IK driven digitigrade legs.
Resonite '''does not''' support Digitigrade legs natively. Many community members have created methods to support them though, such as by using the <code>CopyGlobalTransform</code> component to copy the movements of a dummy plantigrade leg onto non-IK driven digitigrade legs.
{|
|-
|You can add this component to the armature from: <code>Add Component ->[https://wiki.resonite.com/Category:Components:Transform Transform] ->[https://wiki.resonite.com/Category:Components:Transform:Drivers Drivers] ->[https://wiki.resonite.com/Component:CopyGlobalTransform CopyGlobalTransform]</code>
|-
|Note: This component will need to be added to a Digitgrade leg bone that isn't attached to the model, not the existing Plantigrade one. Within the <code>CopyGlobalTransform</code> component we will want to empty/set-to-null the field labeled <code>_posDrive</code> and then copy the Plantigrade leg bone into the <code>Source</code> field of this component.
|}


== Heads == <!--T:38-->
=== Heads ===
Heads are simple, but some data is available to help you in a few areas.
Heads are simple, but some data is available to help you in a few areas.


=== Eyes === <!--T:51-->
==== Eyes ====
Resonite sets up avatars with automatic eye movements and if you have a compatible headset [[Eye Tracking]] is supported. For this to work you'll need eye bones named like so:
Resonite sets up avatars with automatic eye movements and if you have a compatible headset [[Eye Tracking]] is supported. For this to work you'll need eye bones named like so:
{| class="wikitable"
{| class="wikitable"
Line 306: Line 284:
|}
|}


=== Jaws === <!--T:52-->
==== Jaws ====
Jaw bone based animations are possible in Resonite, but are less common due to [[Visemes|Blendshape/Viseme support]], If you'd still like to use a Jaw bone name it "Jaw"('''Case Insensitive''').
Jaw bone based animations are possible in Resonite, but are less common due to [[Visemes|Blendshape/Viseme support]], If you'd still like to use a Jaw bone name it "Jaw"('''Case Insensitive''').


=== [[Visemes]] === <!--T:39-->
==== [[Visemes]] ====
[[Visemes]] are covered elsewhere as they aren't associated with the rig or bones of a model.
[[Visemes]] are covered elsewhere as they aren't associated with the rig or bones of a model.
[[File:IK Rig Head.png|alt=Blender window showing a sample head bone rig layout with a big central bone being named "Head" and two smaller ones in the sides being eyes|thumb|200x200px|Example head rig layout]]


<!--T:40-->
== Overall Summary ==
[[File:HumanoidRigHead.png|thumb|200px|Example head rig layout|alt=Blender window showing a sample head bone rig layout with a big central bone being named "Head" and two smaller ones in the sides being eyes]]
Here are some photos of a summary of the example rig. See above for more detailed notes.


= Overall Summary = <!--T:41-->
If you would like to download this example rig and view it in Blender, it is available [https://www.dropbox.com/scl/fi/in5fdbug53coy7grfjqo9/Resonite_Humanoid_Rig_Example_v1.blend?rlkey=aqzspvopqsvbnxpjgs82ma943&dl=0 Here]
Here are some photos of a summary of the example rig. See above for more detailed notes:


<!--T:42-->
[[File:IK Rig.png|714x714px|Example overall rig]]
[[File:HumanoidRigOverall.png|500px|Example overall rig]]
[[File:IK Rig Bones.png|774x774px|Example overall rig hierarchy shown in blender]]
[[File:HumanoidRigOverallHierarchy.png|250px|Example overall rig hierarchy shown in blender]]


= Supported Tools = <!--T:44-->
== Supported Tools ==
* [https://www.mixamo.com/| Mixamo] generated rigs work well and without any changes.
* [https://www.mixamo.com/ Mixamo] generated rigs work well and without any changes.
* [https://readyplayer.me/| Ready Player Me] avatars work well and without any changes.
* [https://readyplayer.me/ Ready Player Me] avatars work well and without any changes.

Latest revision as of 12:13, 4 September 2024

When you import a rigged model to try and turn it into an avatar, it can be confusing to know what's required and what's not for best results. This page exists to help you understand the requirements.

Supported Formats

If you have a rigged model that's compatible with other VR Platforms such as VRChat etc, then it should work out of the box. Just try importing the avatar.

As a reminder, we don't currently support the importing of .unitypackage / .vrm / .asset / .mesh / .prefab files.

Supported Humanoid Avatar formats:

  • FBX
  • GLTF
  • Blender

Overall Rig/Model Requirements

Definitions

3D Engines and Tools have many different ways to refer to the same thing. To aid in reading this guide, some terms are clarified below for what they mean in Resonite.

  • Segment - A single bone within a Rig. For example if a Finger has 3 Bones, then it has 3 Segments
  • IK - Inverse Kinematics. The system used to pose your Rig in Resonite

General Guidance

  • Your model should be in an A-pose or T-Pose.
  • The Orientation (forward facing direction) of your model should be along the positive Z axis.
    • A flipped Z axis can be detected but might contain bugs.
    • As a quick validation for this:
      • Check the "Force T-pose" option in the advanced import settings. If hands are crossed, rotate 180 degrees along the Z (up-down) axis. If one hand is in front and the other hand is in back, rotate 90 degrees along the Z (up-down) axis.

Ignoring Bones

Sometimes, you might want to ignore a bone in the IK process within Resonite. Luckily you can do this. Simply add <NoIK>(case insensitive) to the Bone's name anywhere within the bone's name. This bone will then not be considered for IK purposes. It's children will though. This is often useful for twist bones or clothing/hair bones that are being detected as skeletal/IK bones.

Bone Name Used in IK? Notes
Right Hand Flagged as a Right Hand
<No_IK> Right Hand Flagged as a Right Hand
<NoIK> Right Hand Ignored by IK
Right Hand <NoIK> Ignored by IK
Right Hand <noik> Ignored by IK
Right Hand <NOIK> Ignored by IK
bo<nOiK>ne Ignored by IK
One day I went to the park, the park had <noik> Ignored by IK

Bone Requirements

When you import a model, Resonite uses pattern matching and heuristics to figure out the layout of your Model's Bones. This means that bone names are largely case insensitive and can have additional data around the name. As an example "hips", "Hips", "HIPS" and "cheese_hips" should all be detected as the model's hip bone. The heuristics are also forgiving of spaces so "upper arm" and "upperarm" should also be flagged correctly as an "Upper Arm" bone.

This is quite good at picking up a variety of rigs but to help you can follow this format.

An extensive guide is presented below, with a key information for each segment of the body.

If this is too much detail you can also skip to a summary.

Central Spine/Hips

The root of the model's armature should be a single hips bone, that faces upwards, see the table below for valid names for it.

Blender viewport showing bones, going from bottom to top: Hips, Spine, Chest and Neck.
Example hip/central spine layout

Following the hips should be a chain that leads from the hips upwards: Hips -> Spine -> Chest -> Neck -> Head.

So in summary:

Order Part Alternative Names Invalid Names (Do Not Use)❌
1st Hips hips, pelvis, root hip
2nd Spine spine, chest
3rd Chest chest, upper chest, ribcage, spine1, spine2
4th Neck neck
5th Head head skull

Upper Chests

Many Avatars have an extra bone segments in the central spine, that's usually called "Upper Chest" or "Spine2".

  1. Hips
  2. Spine
  3. Chest (Sometimes called Spine1)
  4. Upper Chest (Sometimes called Spine2)
  5. Neck
  6. Head

These are NOT required, but we still support these. In these cases the "middle" "Spine" bone will be ignored for the purposes of IK.

Shoulders and Arms

Two arms should be attached to the "Chest" bone from above, one for each side of the model. Use the letters "L" and "R" to indicate which side of the model the arm is on. These are also case insensitive so "l" and "r" are ok.

The order should follow: Shoulder -> Upper Arm -> Lower Arm -> Hand. We'll cover fingers in another segment.

Blender window showing a sample arm bone rig in A-pose.
Example arm rig layout
Order Part Alternative Names
1st Shoulder shoulder, clavicle, collar, collarbone
2nd Upper Arm upperarm, upper arm, arm, bicep
3rd Lower Arm fore arm, forearm, lower arm, lowerarm, elbow
4th Hand hand, wrist, palm

Hands

blender window showing a sample hand bone rig with each individual fingers
Example fingers rig layout

Hands can appear quite complex but they don't need to be. Before we move onto bone names keep in mind the following:

  • Fingers
    • Each finger must have at least two segments.
    • But we support up to 4 segments per finger:
      • Metacarpal
      • Proximal
      • Intermediate
      • Distal
    • We need at least 3 Fingers to identify a hand
  • Thumbs
    • We need an identifiable thumb.

Additionally, if your model has 5 fingers, we'll use geometric detection to figure out what your bones are called. This process looks at the rig and can figure out which finger is which.

Even with these things in mind, you may want to setup the fingers manually. So as with other segments here are some comments on the names of the bones.

For each finger: <fingername>1 -> <fingername>2 -> <fingername>3 -> <fingername>4

Where the finger names are:

  • Thumb
  • Index
  • Middle
  • Ring
  • Pinky

Or explained in a table:

Finger Number Finger Name Alternative Names Example Structure
1 Thumb thumb1.L -> thumb2.L -> thumb3.L -> thumb4.L
2 Index point, pointer index1.L -> index2.L -> index3.L -> index4.L
3 Middle middle1.L -> middle2.L -> middle3.L -> middle4.L
4 Ring ring1.L -> ring2.L -> ring3.L -> ring4.L
5 Pinky little pinky1.L -> pinky2.L -> pinky3.L -> pinky4.L

Finger Identification

Resonite uses the following code to try and find what your fingers are:

public static FingerType? NameToFingerType(List<string> names)
{
    if (names.Contains("thumb") || names.Contains("th") || names.Contains("thm") || names.Contains("thmb"))
        return FingerType.Thumb;
    else if (names.Contains("index") || names.Contains("point") || names.Contains("in") || names.Contains("ind"))
        return FingerType.Index;
    else if (names.Contains("middle") || names.Contains("mid") || names.Contains("mi"))
        return FingerType.Middle;
    else if (names.Contains("ring") || names.Contains("ri") || names.Contains("rin"))
        return FingerType.Ring;
    else if (names.Contains("pinky") || names.Contains("little") || names.Contains("pi") || names.Contains("pin") || names.Contains("pnk"))
        return FingerType.Pinky;

return null;
}

As you can see it's quite flexible and forgiving.

Legs

Legs are simple compared to everything else. Each leg should be connected to the Hip bone. Use the letters "L" and "R" to indicate which side of the model the arm is on. These are also case insensitive so "l" and "r" are ok.

Blender window showing a sample leg bones layout from the side
Example leg rig layout
Order Part Alternative Names
1st Upper Leg upper leg, upleg, thigh, upperleg, hipL, hipR
2nd Lower Leg leg, calf, knee, shin
3rd Foot foot, ankle
4th Toes toe, toes, ball, toebase, toes

Digitigrade Legs

Resonite does not support Digitigrade legs natively. Many community members have created methods to support them though, such as by using the CopyGlobalTransform component to copy the movements of a dummy plantigrade leg onto non-IK driven digitigrade legs.

You can add this component to the armature from: Add Component ->Transform ->Drivers ->CopyGlobalTransform
Note: This component will need to be added to a Digitgrade leg bone that isn't attached to the model, not the existing Plantigrade one. Within the CopyGlobalTransform component we will want to empty/set-to-null the field labeled _posDrive and then copy the Plantigrade leg bone into the Source field of this component.

Heads

Heads are simple, but some data is available to help you in a few areas.

Eyes

Resonite sets up avatars with automatic eye movements and if you have a compatible headset Eye Tracking is supported. For this to work you'll need eye bones named like so:

Part Compatible Names(Case Insensitive)
Left Eye LeftEye, Left Eye, Eye.L,Eye_L
Right Eye RightEye, Right Eye, Eye.R,Eye_R

Jaws

Jaw bone based animations are possible in Resonite, but are less common due to Blendshape/Viseme support, If you'd still like to use a Jaw bone name it "Jaw"(Case Insensitive).

Visemes

Visemes are covered elsewhere as they aren't associated with the rig or bones of a model.

Blender window showing a sample head bone rig layout with a big central bone being named "Head" and two smaller ones in the sides being eyes
Example head rig layout

Overall Summary

Here are some photos of a summary of the example rig. See above for more detailed notes.

If you would like to download this example rig and view it in Blender, it is available Here

Example overall rig Example overall rig hierarchy shown in blender

Supported Tools

  • Mixamo generated rigs work well and without any changes.
  • Ready Player Me avatars work well and without any changes.