Set Up PhysBones for Avatar Secondary Motion
A VRC Phys Bone component animates a transform chain after the avatar moves. Use it for hair, ears, tails, clothing details, straps, and other secondary bones that should react without a hand-authored animation for every movement.
This guide covers one complete chain: choose the root, configure its motion, constrain its range, add only the collision and interaction you need, and verify the result before upload.
Configure and test one representative chain before copying the component to similar bones.
- Select the first dedicated secondary bone and add a VRC Phys Bone component.
- Confirm the affected transforms, then configure forces and limits.
- Test locomotion, poses, collisions, grabbing, and the avatar's component counts.
VRChat warns against assigning hips, spine, chest, upper chest, neck, head, or limb bones as PhysBone roots. Use a dedicated accessory chain or a duplicated root with the secondary children re-parented beneath it.
Video Walkthrough
Use akalink's video for the Unity demonstration and the field reference below while configuring your own chain.
Creator: akalink
Video: Phys Bone Physics
What the Component Affects
The component begins at Root Transform. If that field is empty, it begins at the GameObject that holds the component. Descendants form the simulated chain unless they appear under an ignored transform.
Avatar
└── Armature
└── Head
└── Ear_Phys_Root ← VRC Phys Bone root
└── Ear_01
└── Ear_02
└── Ear_EndKeep the skinned mesh weighted to the same secondary bones. The component moves transforms; the skin weights determine which vertices follow them.
Endpoint requirement
A chain needs a direction and length. Set Endpoint Position when the root has no child, or when it has several direct children with no grandchildren. A non-zero endpoint creates a virtual end after each endpoint in the chain. Adding explicit end bones in the armature is the alternative.
| Transform field | Use |
|---|---|
| Root Transform | Selects the first transform in the simulated hierarchy |
| Ignore Transforms | Excludes a transform and all of its children |
| Ignore Other Phys Bones | Prevents nested PhysBone chains from being affected by the parent component; enabled by default |
| Endpoint Position | Adds a virtual endpoint when the hierarchy does not provide one |
| Multi-Child Type | Determines how a root behaves when it branches into multiple child chains |
Choose the Multi-Child Behavior
When one root has several branches, Multi-Child Type determines whether that root participates in the motion.
| Mode | Root behavior | Suitable case |
|---|---|---|
| Ignore | Root stays fixed while each child branch moves | Several hair strands grouped under one fixed root |
| First | Root continues into the first branch | One primary chain plus additional branches |
| Average | Root follows the average motion of its branches | A branching structure whose shared base should move |
For a single unbranched chain, this choice does not need to carry the design.
Select an Integration Type
The current VRC Phys Bone component offers two force models.
| Integration Type | Available response controls | Behavior |
|---|---|---|
| Simplified | Pull and Spring | More stable and less reactive to external impulses |
| Advanced | Pull, Momentum, and Stiffness | More reactive and supports more involved configurations |
New components use the latest PhysBone version by default. Existing components retain their selected version until you change it and re-upload the avatar. Version 1.1 includes squish and motion-driven length changes, and it changes how Gravity and Stiffness are evaluated.
Configure the Forces
Change one field, run the same movement test, and compare the result. The field names have specific meanings:
| Field | Effect |
|---|---|
| Pull | Returns bones toward their rest position |
| Spring | Adds wobble while returning to rest in Simplified mode |
| Momentum | Adds wobble while returning to rest in Advanced mode |
| Stiffness | Preserves the previous orientation in Advanced mode |
| Gravity | Pulls bones down with a positive value or upward with a negative value |
| Gravity Falloff | Reduces gravity while the chain is at its rest position |
| Immobile | Dampens motion according to the selected Immobile Type |
Gravity Falloff is useful when the modeled rest pose should remain visible while gravity still affects the chain away from that pose. In PhysBone version 1.1, positive Pull is required for Gravity to move the bones toward the gravity direction.
Constrain the Range of Motion
Limits restrict the directions a chain can move and display a Scene view visualization while the component is selected.
| Limit Type | Shape | Use |
|---|---|---|
| None | Unrestricted | Chains that do not need directional control |
| Angle | Cone | Similar pitch and yaw ranges around one axis |
| Hinge | Circular slice | Motion mainly along one plane |
| Polar | Spherical segment | Different pitch and yaw ranges |
Use Angle instead of Polar when the pitch and yaw range can be the same. VRChat notes that Polar limits have a performance cost. A suitable limit can also prevent clipping more efficiently than adding a collider.
Add Collision Only Where It Solves a Contact
The PhysBone's Radius defines the collision radius around its bones and is also used for grabbing. With a radius of zero, the chain has no area for those interactions.
Allow Collision determines which colliders can affect the chain:
| Value | Collision behavior |
|---|---|
| True | Includes applicable global colliders, such as player hands |
| False | Uses only colliders assigned in the component's Colliders list |
| Other | Exposes filters for this avatar and other avatars or worlds |
A VRC Phys Bone Collider can be a Sphere, Capsule, or Plane. Avatar Descriptor standard colliders are available for the head, torso, hands, feet, and fingers; VRChat sets them up automatically unless they are customized.
Use a collider for a concrete boundary, such as hair against the head. Use a limit when the problem is excessive rotation rather than contact with a shape.
Configure Grabbing and Posing
Interaction is controlled independently from the motion:
| Field | Behavior |
|---|---|
| Allow Grabbing | Lets the wearer, other users, or both grab the chain according to the selected filter |
| Allow Posing | Lets an allowed user hold the chain in a posed position after grabbing |
| Grab Movement | Blends between force-driven movement at 0 and immediate movement to the hand at 1 |
| Snap To Hand | Moves a grabbed bone to the grabbing bone |
Disable grabbing or posing when the chain is visual motion only. If interaction is enabled, test the self and others permissions separately.
Setting the component's Parameter field to a prefix such as Ear provides Ear_IsGrabbed, Ear_IsPosed, Ear_Angle, Ear_Stretch, and Ear_Squish. VRChat generates these values on local and remote clients, so they do not need entries in the VRC Expression Parameters asset.
Run a Consistent Motion Test
Use the same sequence after each meaningful change:
| Test | Check |
|---|---|
| Rest pose | The chain returns to the modeled direction without a persistent offset |
| Head or body turn | The follow-through matches the intended accessory |
| Walk and stop | The chain settles without uncontrolled oscillation |
| Crouch and stand | Gravity and Immobile behavior remain predictable |
| Extreme avatar pose | Limits prevent impossible rotation |
| Intended collider contact | The chain stays outside the required boundary |
| Grab and release | Permissions, Radius, Grab Movement, and return motion work |
| Pose and unpose | The chain locks and releases only when posing is allowed |
If a change fixes one test and breaks another, revert that field before adjusting a second setting.
Check Avatar Performance
VRChat's performance rank counts PhysBone components, affected transforms, colliders, and collision checks separately. Disabled GameObjects and components still count toward the rank.
For PC avatars, the current Good thresholds are:
| PhysBone statistic | Good maximum |
|---|---|
| Components | 8 |
| Affected transforms | 64 |
| Colliders | 8 |
| Collision check count | 128 |
Mobile avatars have hard component limits. Exceeding any of these removes all PhysBone, PhysBone Collider, Contact, and VRChat Constraint components from the avatar in VRChat, regardless of Show Avatar:
| Mobile hard limit | Maximum |
|---|---|
| PhysBone components | 8 |
| Affected transforms | 64 |
| PhysBone colliders | 16 |
| PhysBone collision checks | 64 |
A single PhysBone component cannot affect more than 256 transforms. VRChat also recommends splitting a component when its affected transform count grows beyond roughly 128 so the work can be distributed across threads.
Troubleshooting
Help! The chain does not move.
Confirm Root Transform points to the intended secondary chain. If the root has no child, or only direct children without grandchildren, assign a non-zero Endpoint Position or add explicit end bones.
Help! The chain moves in an unexpected direction.
Inspect the bone hierarchy and rest orientation first. Then verify the selected PhysBone version, Gravity, Gravity Falloff, and the Scene view visualization for the active limit.
Help! The accessory keeps clipping through the avatar.
Add an Angle, Hinge, or Polar limit when the chain is rotating too far. Add a collider only when the motion must stop at a physical boundary such as the head or torso.
Help! I cannot grab the PhysBone.
Check that Allow Grabbing includes the user performing the test and that Radius is greater than zero. Also confirm that the chain is enabled and its bones lie within the component's interaction bounds.
Help! An animation on the chain is ignored.
Enable Is Animated on the VRC Phys Bone. This updates the rest position from animation each frame so the root and affected transforms can respect animated motion.
Help! A constrained bone jitters or behaves inconsistently.
Do not place a Constraint and a PhysBone on the same affected GameObject. VRChat documents execution-order problems for that arrangement; place the Constraint on the parent and keep its source aimed at the intended transform.
Help! PhysBones disappear from the mobile avatar.
Check all four mobile component totals in the SDK: components, affected transforms, colliders, and collision checks. Exceeding a mobile hard limit removes the limited avatar components instead of preserving only the chains below the cap.
Official VRChat References
Continue with Avatar Dynamics
- Use PhysBone Grabbing, Posing, and Parameters
- Toggle Avatar Props with a PhysBone Grab Handle
- Build Hold-to-Activate Avatar Contacts
- Test Avatar Dynamics at Four Levels
- Avatar Optimization Checklist
- Avatar Creation Guides
Topics: PhysBones, avatar secondary motion, colliders, grabbing, performance
