​​Angle

Anglemeans the bone chain will be limited to someMax Angle, centered on an axis as defined byRotation. This is visualized as a Cone in the Scene view.

---

Hinge

Hingemeans that the bone chain will be limited to someMax Anglealong the plane defined by theRotation. This is visualized as a slice of a circle, similar to a pizza or a pie.

---

Polar

Polaris a bit more complicated. If you take aHingeand sweep it acrossYawby some amount, you get a segment of a sphere inPolarcoordinates. You can configureMax PitchandMax Yawto adjust the size of the segment, and useRotationto define where that segment is located on the sphere. The visualization forPolaris especially helpful.

Don't overuse Polar limits, as they have a non-zero performance cost. Using a huge amount (handwaving: more than 64) will probably cause some issues. If yourMax PitchandMax Yawvalues are similar or the same, anAnglelimit will suffice and costs less performance-wise.

---

Collision

Radius- Collision radius around each bone in meters. Used for both collision and grabbing.
Allow Collision- Allows collision with colliders other than the ones specified on this component. Currently the only other colliders are each player's hands and fingers as defined by their avatar.
Colliders- List of colliders that specifically collide with these bones.

---

Grab & Pose

Allow Grabbing- Allows players to grab the bones.
Allow Posing- Allows players to pose the bones after grabbing.
Grab Movement- Controls how grabbed bones move. A value of zero results in bones using pull & spring to reach the grabbed position. A value of one results in bones immediately moving to the grabbed position.
Max Stretch- Maximum amount the bones can stretch when being grabbed. Actual length based on each bone's original rest length.

---

Options

Parameter- Prefix used to provide multiple parameters to the avatar controller. In the following items, setting Parameter toTailwould replace{parameter}withTail

{parameter}_IsGrabbed
[Bool] Are the bones currently being grabbed.

{parameter}_Angle
[Float] Range of 0.0-1.0. Normalized 180 angle made between the end bone's is from its original rest position. In other words, if you twist a bone completely opposite of its start direction, this param will have a value of 1.0.

{parameter}_Stretch
[Float] Range of 0.0-1.0. How close the bones are to their maximum stretch length.

Is Animated- Allows bone transforms to be animated. Each frame bone rest position will be updated according to what was animated.

---

Important Notes, Usage Tips, etc

❗️

PhysBones have a hard limit on the Meta Quest.This is done to prevent a reduction in performance on the Meta Quest devices, which are often already low on CPU resources.

You can view those limits as the Very Poor limits for Quest described in theMinimum Displayed Performance Rankdocumentation.

---

Per-Component Limitations

A single PhysBone component cannot affect more than 256 transforms at a time.This counts the root bone as well as all children.This also affects Dynamic Bone conversions!

However, you should aim not to have that many transforms to animate in the first place. Try merging bones in the chain upward to their immediate parents. Community-created tools like Cat's Blender Plugin can do this for you.

---

Animating Properties

PhysBone properties like Spring, Pull, Stiffness, etc are set at initialization andcannot be animated.

However, if you animate a property of a PhysBone component and then animate the component off and then on, youmayget the behavior you want. Be aware that this is not a support method of animating these properties, and will not be supported in future changes. (In other words, it might break. If it does, we're not going to try to fix it.)

---

Humanoid Bones

Do not set Humanoid bones as PhysBone Root bones.In other words, do not set Hip, Spine, Chest, Upper Chest, Neck, Head, or any of the limb bones as Roots. This will cause major issues.

Instead, duplicate the bone you want to use as root and re-parent all the children bones you want to animate to that new duplicate root. This should be done in Blender. Community-created tools like Cat's Blender Plugin can do this for you.

---

PhysBone Rotation

Unlike Dynamic Bones,the root bone of a PhysBone chain is permitted to rotate.It can't translate, though. This can have some consequences with certain setups-- try things out on your own to see how it behaves.

---

PhysBone AV3 Parameters

When affecting parameters,there is no need to use Synced Parameters as defined by theVRCExpressionParametersobject. These parameters are already updated on both the local and remote machines, as both will be running PhysBones.

---

PhysBone Immobile Behavior

Dynamic Bones bases itsInertvalue from where the component is placed, not the root transform. This is probably a Dynamic Bones bug. As such, PhysBones bases itsImmobilevalue from the root transform. This may affect behavior in some cases.

---

Optimal Component Usage

Because of the multi-threaded nature of PhysBones, it isn't always the most efficient to put all bones into a single chain. Multiple components allows us to break up the work across threads. However, you should still strive to have fewer components... but it's not as bad to have a few on your avatar as it was with Dynamic Bones.

If youreallyneed a number, you should consider splitting sets of chains when you're getting over 128 transforms affected by a single component. If you have a dress with 256 bones and it splits at a root, splitting it into two or three components will work.

However, if you're just dealing with something on the order of 32 bones... don't worry about it. As you can probably tell, these aren't strict rules! We'll likely introduce some soft warnings later on when something looks like it should be set up a different way.​​​​