Last reviewed 31 Jul 2026

Applies to

VRChat Avatar SDK Legacy Dynamic Bone avatars VRC Phys Bone

Difficulty Intermediate

Convert Dynamic Bones to VRChat PhysBones

Dynamic Bone is deprecated for VRChat avatars. Current avatars should use VRC Phys Bone and VRC Phys Bone Collider components for secondary motion, grabbing, posing, and collision.

VRChat automatically generates PhysBones at runtime for older uploaded avatars that still contain Dynamic Bone components. For an avatar you can edit, convert the project yourself so you can inspect the result, correct its motion, and measure its performance before uploading.

Before Conversion

The SDK converter deletes the Dynamic Bone components it replaces. VRChat describes the conversion as difficult to reverse, so preserve an untouched copy first.

1. Close Unity and make a project backup, or duplicate the avatar and its scene.
2. Open the avatar project through VRChat Creator Companion.
3. Update the project packages through Creator Companion when required by the SDK.
4. Confirm the intended avatar is active in the open scene.
5. Record or capture the original motion so you have a comparison target.
6. Note which chains use Dynamic Bone colliders, exclusions, gravity, or force.
7. Resolve red Unity Console errors before running the converter.

If the original avatar package includes a supported PhysBone version, install or use that version instead of converting the legacy setup.

Run the SDK Converter

Select the avatar in the Hierarchy, then use either conversion entry exposed by the current SDK:

• the Dynamic Bone conversion control in the SDK Builder panel, or
• VRChat SDK > Utilities > Convert DynamicBones to PhysBones

The utility creates PhysBone equivalents and removes the converted Dynamic Bone components. After it finishes:

1. Search the avatar hierarchy for VRC Phys Bone components.
2. Search for VRC Phys Bone Collider components.
3. Confirm each component uses the intended Root Transform.
4. Check the affected bone chains in the Scene view with PhysBone gizmos enabled.
5. Save the converted avatar as a new prefab or scene before retuning it.

What Does Not Convert Exactly

Automatic conversion aims to produce a usable starting point, not identical motion.

Legacy behaviour	PhysBone migration result
Dynamic Bone Gravity or Force on X or Z	Ignored because there is no equivalent conversion.
Dynamic Bone Inert	PhysBone Immobile is calculated from the root transform, so motion can differ.
Custom collision behaviour	Requires inspection of collider assignments, radius, and collision permissions.
Dynamic Bone response values	Converted values may need manual tuning because the simulation models differ.

Do not judge the conversion only by matching Inspector numbers. Compare the motion in play mode and in a local VRChat test build.

Check the PhysBone Chain

Select each converted component and verify its structure first.

Setting	Check
Root Transform	The first transform in the intended moving chain.
Ignore Transforms	Bones that should remain outside the simulation.
Endpoint Position	A usable endpoint when the final bone has no child transform.
Multi Child Type	How a branching hierarchy should be interpreted.
Is Animated	Enable only when animation also changes transforms in this PhysBone chain.
Reset When Disabled	Whether the chain should return to its rest position when the component is disabled.

A single PhysBone can affect a root and its descendants. One component may cover several branches, such as multiple hair chains beneath a shared root, when that structure produces the intended result.

Retune the Motion

PhysBone motion is controlled by a group of related properties. Change one category at a time and test after each pass.

Pull, Spring, and Stiffness

• Pull moves bones back toward their rest position.
• Spring controls oscillation around the rest position.
• Stiffness resists changes away from the rest pose.

Begin with the converted values, then adjust gradually. A chain that never settles usually needs less spring, more pull, more stiffness, or a combination appropriate to the asset.

Gravity and Immobile

• Gravity adds a downward or upward influence.
• Immobile controls how much movement of the PhysBone root contributes to the simulation.

Because PhysBone Immobile is based on the root transform, moving the component to another GameObject can change the result even when the visible bone chain is the same.

Limits

Use a limit when a chain should only move through a controlled range:

• Angle limits motion within a cone.
• Hinge restricts motion to a plane.
• Polar provides separate pitch and yaw ranges.

VRChat recommends limits for cases such as preventing hair from clipping into the head because limits can be more performant than adding a collider. Use the Scene view visualization to align the limit with the chain.

Avoid using Polar when Angle provides the same usable range. Polar limits have additional performance cost.

Review Collision, Grabbing, and Posing

For each PhysBone, inspect:

• Radius, which affects collision and grabbing around the bones
• Allow Collision, including whether global or explicitly listed colliders can affect it
• the Colliders list
• Allow Grabbing and its self/others permissions
• Allow Posing and its self/others permissions
• Grab Movement and Snap To Hand

Remove colliders that do not solve a visible problem. Each collider can be checked against multiple affected transforms, increasing the avatar's PhysBones collision check count.

Avatar interaction is also governed by each player's VRChat permissions and settings. A correct component setup does not force another user to allow grabbing, posing, or collision.

Avoid Component Conflicts

Do not place a Constraint and a PhysBone on the same GameObject. VRChat warns that this creates execution-order issues.

When both behaviours are required, place the Constraint on the parent GameObject and keep its source transform pointed at the intended transform, following the current PhysBones documentation.

Also check that:

• the same transform is not controlled by overlapping PhysBone components
• animation does not fight the chain unless Is Animated is intentionally enabled
• colliders do not start inside the PhysBone radius
• a disabled component resets as intended

Optimize the Converted Setup

The SDK's avatar statistics separate PhysBone cost into:

• PhysBones Components
• PhysBones Affected Transforms
• PhysBones Colliders
• PhysBones Collision Check Count

All avatar GameObjects and components count toward Performance Rank even when disabled.

Use these metrics to guide changes:

1. Remove converted chains the avatar does not need.
2. Reduce unnecessary bones in dense chains.
3. Reuse a sensible shared root where one component can cover related branches.
4. Split unusually large branching chains when that improves threading and control.
5. Prefer movement limits over collision where a limit solves the same clipping problem.
6. Remove unused colliders and narrow collider assignments.
7. Recheck the Builder statistics after every structural change.

A single PhysBone component cannot affect more than 256 transforms, including its root and children. VRChat advises considering multiple components when a single setup grows beyond roughly 128 affected transforms, while still aiming to avoid needless components.

Test the Converted Avatar

Use the SDK's local avatar test build before publishing.

Test each chain for:

• motion while standing, walking, running, jumping, and turning
• recovery after rapid movement
• clipping through the head, body, or clothing
• correct limits across the full intended range
• self and other-user collision permissions
• grabbing, releasing, posing, and reset behaviour
• animated states that enable, disable, or move the chain
• the Android or iOS build when the avatar supports mobile platforms

In VRChat, the Avatar Overlay can display PhysBones and Contacts while you debug avatar components.

Troubleshooting

The SDK converter is unavailable or does not detect the avatar.

Confirm the project contains the current VRChat Avatars SDK, select the avatar root in the open scene, and resolve Unity compiler errors. The conversion tool requires an avatar containing detectable Dynamic Bone components.

The converted hair moves much more than the Dynamic Bone version.

Check Pull, Spring, Stiffness, Gravity, and Immobile rather than copying legacy values directly. Then add an Angle or Hinge limit where the chain should have a defined movement range.

The chain bends in the wrong direction.

Inspect the root and child bone orientations, then select the PhysBone and align its limit rotation using the Scene view gizmo. Confirm the Endpoint Position is sensible when the final bone has no child.

The PhysBone starts inside the head or body.

Reduce or reposition its radius, inspect listed colliders, and check whether a collider overlaps the chain in its rest pose. Use a movement limit instead when the goal is simply to keep the chain within a known range.

Grabbing or posing does not work for another player.

Check Allow Grabbing, Allow Posing, and the self/others filters on the component. The other player must also permit the interaction through their VRChat permissions and settings.

An animation and PhysBone fight over the same chain.

Enable Is Animated when the chain's transforms must follow animation, then test the result. Also remove overlapping transform control from other PhysBones or Constraints on the same GameObject.

The PhysBones disappear on the mobile avatar.

Review the mobile PhysBone component, affected-transform, collider, and collision-check counts in the SDK. Exceeding an enforced mobile limit causes VRChat to remove the limited components at runtime.

I need to restore the original Dynamic Bone setup.

Restore the untouched project, prefab, or scene backup made before conversion. The converter removes the legacy components, and recreating their exact configuration manually may not be practical.

Migration Checklist

• The original project or avatar is backed up.
• Dynamic Bone components were used only as conversion input.
• Every converted root and affected chain is intentional.
• Unsupported Gravity and Force behaviour has been retuned.
• Limits, radius, collisions, grabbing, and posing are reviewed.
• No Constraint shares a GameObject with a PhysBone.
• Unused components, transforms, and colliders are removed.
• Builder performance metrics meet the intended platform target.
• Mobile hard limits are respected where applicable.
• The avatar has passed an in-client local test.

Official References

• VRChat Creation: PhysBones
• VRChat Creation: Allowed Avatar Components
• VRChat Creation: Avatar Components
• VRChat Creation: Debugging Avatar Components
• VRChat Creation: Avatar Performance Ranks
• VRChat Creation: Android Content Limitations

Related Guides

• Set Up PhysBones for Avatar Hair, Tails, Ears, and Clothing
• Avatar Dynamics: Senders, Receivers, and Grabbing
• Test Avatar Dynamics
• Avatar Optimization Checklist
• Quest and Mobile Compatibility Checklist
• VRChat Documentation