Set Up PhysBones on a VRChat Avatar
VRCPhysBone animates a transform chain to create secondary motion on avatar hair, ears, tails, clothing, wires, straps, and similar parts. A PhysBone can also support collision, grabbing, and posing when its component settings and the users' interaction permissions allow those behaviours.
Configure one visible chain and verify its root, endpoint, movement, and limits before reusing the settings.
- Add
VRCPhysBoneto the intended chain root and inspect every affected transform. - Configure forces and a movement limit, then add collision only when the part needs it.
- Build and test motion, grabbing, posing, and performance in VRChat.
Video creator: DedZedOffishal
Do not use a mapped Humanoid bone such as Hips, Spine, Chest, Neck, Head, or a limb bone as the PhysBone root. VRChat warns that this causes major problems. Secondary-motion chains should branch from suitable non-Humanoid bones.
Understand the Transform Chain
A PhysBone component begins at Root Transform. If that field is empty, it begins at the GameObject that holds the component. It then follows descendants in the hierarchy unless transforms are excluded.
Before adding the component:
- Expand the intended chain in the Hierarchy.
- Identify its root, intermediate bones, and final child.
- Check for unexpected branches.
- Confirm that the chain does not begin on a mapped Humanoid bone.
- Note any children that must be excluded.
Root and endpoint rules
| Chain structure | Required check |
|---|---|
| Root with a normal child chain | Confirm the children follow the intended order |
| A single root bone with no child | Set a non-zero Endpoint Position |
| Root with several children but no grandchildren | Set a non-zero Endpoint Position |
| Root with several full chains | Select the appropriate Multi-Child Type |
| Chain containing another PhysBone | Keep Ignore Other Phys Bones enabled unless the hierarchy has a documented reason not to |
VRChat specifically requires an endpoint for a single bone or a single root with several children but no grandchildren. An alternative is to add end bones in the armature.
Add the VRCPhysBone Component
- Select the intended chain root in the Hierarchy.
- Select Add Component in the Inspector.
- Add VRC Phys Bone.
- Leave Root Transform empty when the component is attached directly to the intended root.
- Otherwise, assign the intended root explicitly.
- Expand the hierarchy and verify the affected descendants.
- Add unrelated branches to Ignore Transforms.
- Configure Endpoint Position when the chain structure requires it.
Ignored transforms include all of their children. Check the complete excluded branch before continuing.
Select the Component Version
New components use the latest PhysBone version by default. Existing components remain on their previous version until they are manually updated and the avatar is uploaded again.
Current version behaviour documented by VRChat includes:
| Version | Notable behaviour |
|---|---|
| 1.0 | Original PhysBone behaviour |
| 1.1 | Stretch and squish support; revised gravity and stiffness behaviour |
Changing the version can alter an existing chain. Record or duplicate working settings before updating a component, then test the re-uploaded avatar.
Select an Integration Type
PhysBones provide two force-integration modes:
| Integration Type | Behaviour |
|---|---|
| Simplified | More stable, less reactive to external impulses, and easier to configure |
| Advanced | More reactive and configurable, but less stable |
For a new chain, use Simplified unless the motion requires Advanced-only controls.
Simplified force controls
- Pull returns bones towards their rest position.
- Spring controls wobble while the bones return.
- Gravity applies a downward or upward rotational influence.
- Gravity Falloff reduces gravity at the rest position.
- Immobile reduces motion inherited from movement of the root's parent according to the selected Immobile Type.
Advanced force controls
- Pull returns bones towards their rest position.
- Momentum provides wobble under the Advanced integration model.
- Stiffness keeps bones near their previous orientation.
- Gravity, Gravity Falloff, and Immobile provide the corresponding directional and movement controls.
Change one control at a time and observe the chain while the avatar walks, turns, crouches, and moves its head or limbs.
Configure Movement Limits
Limits restrict the area a chain can enter and can prevent clipping without adding a collider. VRChat notes that limits are more performant than colliders.
| Limit Type | Use |
|---|---|
| None | No movement restriction |
| Angle | Motion inside a cone around the configured axis |
| Hinge | Motion along one configured plane |
| Polar | Separate pitch and yaw ranges in a spherical segment |
Select the component in the Scene view and enable Gizmos to inspect the limit visualization.
Use Angle when pitch and yaw ranges can be similar. VRChat advises against excessive Polar limits because Polar has a non-zero performance cost.
Configure Collision
Radius defines the collision and grabbing radius around the affected bones. Increase it only enough to cover the intended part.
Allow Collision controls what can collide:
| Setting | Collision behaviour |
|---|---|
| True | Uses global colliders, including player hands and eligible avatar or world colliders |
| False | Uses only colliders assigned in this component's Colliders list |
| Other | Exposes additional filters for collisions from this avatar, other avatars, or worlds |
Add a VRCPhysBoneCollider
- Select a stable avatar transform such as an appropriate torso or head helper.
- Add VRC Phys Bone Collider.
- Select Sphere, Capsule, or Plane.
- Set its radius, height, position, and rotation.
- Add the collider to the intended PhysBone component if it is not global.
- Check the collider gizmo from multiple angles.
- Test whether the movement limit can replace the collider.
Avatar colliders with Global Collision enabled are limited, and global collision is supported only for Sphere and Capsule shapes.
The performance system counts PhysBone colliders and collision checks separately. A collision check can count the same transform more than once when several colliders affect it.
Configure Grabbing and Posing
PhysBones can let the wearer or other users grab a chain. Posing holds the grabbed chain in position.
| Setting | Purpose |
|---|---|
| Allow Grabbing | Controls whether the wearer, other users, or both can grab the chain |
| Allow Posing | Controls whether an allowed grab can be held as a pose |
| Grab Movement | Blends between force-driven movement and immediate movement to the grabbed point |
| Snap To Hand | Moves the grabbed bone directly to the grabbing bone |
Other users also need compatible avatar-interaction permissions. A correct component cannot override the interacting user's client settings.
Disable grabbing and posing when the avatar part is not intended to be handled.
Use PhysBone Animator Parameters
The optional Parameter field is a prefix for built-in PhysBone animator values. If the prefix is Tail, VRChat provides:
| Parameter | Type | Meaning |
|---|---|---|
Tail_IsGrabbed |
Bool | The chain is currently grabbed |
Tail_IsPosed |
Bool | The chain is held in a pose |
Tail_Angle |
Float | Normalized angle from the rest direction |
Tail_Stretch |
Float | Normalized progress towards maximum stretch |
Tail_Squish |
Float | Normalized progress towards maximum squish |
VRChat states that these values do not need to be added as synced parameters in the avatar's VRCExpressionParameters asset. Use them only when an Animator Controller needs to react to the chain.
Animation and Constraint Conflicts
Enable Is Animated when animation clips must change the rest position of transforms in the PhysBone chain. VRChat states that this must be enabled for the root or any affected bone to respect animations applied to it.
Do not place a constraint and a PhysBone on the same GameObject when both affect that transform. VRChat documents execution-order problems in that arrangement. Move the constraint to the parent GameObject and keep its source transform pointed at the intended object.
PhysBone force properties are initialized rather than designed for normal avatar animation. Do not build an avatar feature around animating Spring, Pull, Stiffness, or similar component properties.
Performance Checks
The VRChat performance system measures four PhysBone categories:
| Metric | What is counted |
|---|---|
| PhysBones Components | Number of VRCPhysBone components |
| PhysBones Affected Transforms | Total transforms controlled by PhysBones |
| PhysBones Colliders | Number of PhysBone collider components |
| PhysBones Collision Check Count | Total transform-versus-collider checks |
All GameObjects and components count towards avatar performance rank, including disabled ones.
One PhysBone component cannot affect more than 256 transforms. VRChat also publishes stricter mobile limits. If a mobile avatar exceeds its hard component limits, the limited components are removed in VRChat even when a user selects Show Avatar.
Use the SDK Builder's reported statistics as the source of truth for the completed avatar.
Test the Chain
Build the avatar and check:
| Test | Expected result |
|---|---|
| Idle | The chain settles into the intended rest shape |
| Walking | Motion follows the avatar without uncontrolled oscillation |
| Turning | Hair, tails, or accessories do not cross the body unexpectedly |
| Crouching | Limits still prevent major clipping |
| Gesture or animation | Animated rest positions work only where intended |
| Collision | The chain reacts to only the configured collision sources |
| Self grab | The wearer can grab only when allowed |
| Remote grab | Other users can interact only when both component and user permissions allow it |
| Pose release | The chain returns correctly after a pose is released |
| Performance | SDK PhysBone metrics remain within the target platform requirements |
Troubleshooting
The PhysBone component is present but nothing moves.
Confirm that Root Transform points to the intended hierarchy and that the chain contains affected transforms. A single bone or a root with only leaf children also needs a non-zero Endpoint Position.
The wrong bones move with the chain.
Inspect every descendant under Root Transform. Add unrelated branches to Ignore Transforms or move the component to a more specific root.
The chain swings through the avatar's body.
Configure an Angle, Hinge, or Polar limit first. Add a correctly sized collider only where a movement limit cannot describe the required boundary.
The chain vibrates or becomes unstable.
Check for excessive force settings, overlapping collisions, constraints on the same transforms, and multiple PhysBones affecting the chain. Compare the result with Simplified integration.
Animations no longer move a PhysBone transform.
Enable Is Animated on the PhysBone when animation clips must update the rest position of its root or affected bones. Then retest every animation that touches the chain.
Other users cannot grab or pose the chain.
Check Allow Grabbing and Allow Posing for other users, the collision radius, and both users' avatar-interaction permissions. A posed interaction also requires a successful grab.
The avatar's performance rank became worse.
Read the four PhysBone metrics in the SDK Builder. Remove unused components and colliders, reduce affected transforms, and replace suitable collisions with movement limits.
PhysBones disappear from the mobile avatar.
Compare the mobile build against VRChat's current mobile component limits. Exceeding a hard PhysBone, transform, collider, or collision-check limit causes the limited components to be removed in VRChat.
Next Steps
- Toggle PhysBones from the Expressions Menu
- Create a world-fixed avatar prop
- Review the avatar optimization checklist
- Check Android and Quest compatibility
- Return to the Avatar Creation guides
Official References
- VRChat: PhysBones
- VRChat: Avatar Components
- VRChat: Debugging Avatar Components
- VRChat: Avatar Performance Ranks
- VRChat: Android Content Limitations
Topics: VRChat PhysBones, VRCPhysBone, Avatar Dynamics, PhysBone colliders, grab and pose
