VRChat has quickly become one of the most popular platforms for immersive, avatar-based social experiences, allowing users to interact, create, and explore in custom virtual worlds. A major feature that enhances the realism of avatars in VRChat is the use of PhysBones — dynamic bone systems that simulate soft body movement, like hair, tails, ears, or wings. But what happens when your cool physics-driven appendages suddenly stop responding? If you’re wondering why your PhysBones are broken, you’re not alone — and this guide is here to help.
TL;DR
If your VRChat PhysBones aren’t working, the issue could lie in how they are configured in Unity, how they’re being affected by avatar scaling, or if they’ve been disabled due to incorrect settings. Begin by checking your Unity import, verify collisions and constraints, and ensure you’re using the correct VRChat SDK. Most problems trace back to simple configuration mistakes or outdated content.
What Are PhysBones?
PhysBones are a replacement and upgrade for the older Dynamic Bones system. They are officially supported by VRChat and provide features like improved performance, more realistic physics simulation, and better compatibility across devices.
With PhysBones, avatar parts like ponytails, tails, and clothing accessories can react naturally to player movements and even the virtual environment. However, because they’re more complex, issues can arise during setup or editing that might stop them from working correctly in VRChat.
Common Signs Your PhysBones Are Broken
- Hair, tail, or clothing physics not moving or reacting to motion.
- Parts of the avatar appear rigid when they should be flexible.
- Avatar works in Unity but parts instantly freeze in VRChat.
- Warnings or errors appear in the VRChat SDK console related to PhysBones.
Root Causes and Troubleshooting Steps
1. Incorrect Setup in Unity
This is by far the most common culprit. If the PhysBone components are not configured properly before uploading your avatar, VRChat won’t know how to simulate the physics.
Check the following:
- Ensure you’re using the official VRChat SDK 3.0.
- Use the VRChat Avatar Descriptor properly and make sure you assigned the PhysBones to the right bones or transforms.
- Open the VRChat control panel in Unity and check for any errors or warnings on upload. Red flags usually indicate incorrect PhysBone references or missing colliders.
A good rule of thumb is to always test bones using the avatar Play Mode in Unity to verify that they move how you expect them to.
2. Missing or Misplaced Collider Objects
PhysBones require appropriate colliders to simulate interactions — with the avatar’s body or with the world.
To fix collider issues:
- Ensure that you’ve added VRChat PhysBone Colliders to the avatar where collisions should be detected (such as the hips, chest, hands).
- Confirm the Collider Match settings; incorrect sizes or misaligned colliders can cause PhysBones to become stuck or behave oddly.
- If parts move erratically or jiggle endlessly, the colliders may be too close, resulting in constant collision states.
3. Scaling and Parenting Issues
One of the lesser-known issues with PhysBones has to do with parenting structure and scale. If any part of the bone chain is unevenly scaled or sits under a non-uniform transform, it can break physics simulation.
Best practices include:
- Avoid placing PhysBones under non-uniformly scaled game objects.
- Use default (1,1,1) scale for the parent of the PhysBone structure.
- Don’t change the avatar’s scale in Unity — scale should be applied properly via bone proportions and not via transform scaling.
You can verify the hierarchy of your avatar in Unity’s inspector and look for suspicious scaling or misaligned bones.
4. Incorrect Animation Overrides
If you’re using animations that override bone positions (via custom animations or emotes), those can potentially interfere with how PhysBones behave. Specifically, if you’re resetting transform positions each frame via an animation, physics won’t apply correctly.
What to check:
- Test the avatar without any animation layers temporarily.
- Review custom animations in your FX layer — ensure they aren’t affecting PhysBone transforms.
- Use editable states or transitions that disable conflicting animations if needed.
5. Outdated or Converted Avatars
Many users ported over all their customized Dynamic Bone rigs into the new PhysBone system using auto-converters or manual updates. This can lead to partial conversions or broken links.
To troubleshoot:
- Double check PhysBone components have been fully added and configured — not just converted from Dynamic Bone.
- Look through all attached components to remove any lingering Dynamic Bone scripts.
- Consider starting fresh on a bone chain if behavior seems erratic after conversion.
Debugging PhysBones in Unity
The Unity editor offers a visual way to test and refine PhysBones. Using “Play Mode,” you can see how bones react to movement, tweak damping and pull, and test collisions.
Tips for Unity testing:
- Make use of the Gizmo display to see bone curves and influence ranges.
- Test each PhysBone individually with exaggerated motion to ensure it reacts.
- Try changing values like Damping, Stiffness, and Pull to tune the responsiveness.
When In-World Bones Don’t Match Unity
Sometimes everything looks correct in Unity, but collapses or fails when loaded inside VRChat. This is often caused by:
- Wrong upload pipeline (using the wrong version of VRChat SDK).
- Shader-based animations conflicting with PhysBone-moved accessories.
- Settings that unintentionally disable avatar features (like restrict bone movement or limits on cloth simulation).
Try uploading the avatar with PhysBones simplified, and then incrementally re-enable features to pinpoint the issue.
Useful Tools and Resources
- VRChat PhysBones Documentation – Official guide with setup examples and parameters explained.
- VRChat Discord – Get help from the community in real-time.
- VRLabs Avatar Tools – Tools for fixing and managing PhysBones and avatars efficiently.
Final Thoughts
PhysBones can add an incredible layer of realism and personal flair to your VRChat avatars, but only if set up correctly. Many issues boil down to configuration problems — missed components, wrong values, or incorrect hierarchies. The good news is that most of these issues can be fixed with a bit of informed tweaking in Unity.
With the right troubleshooting process and a few patience-fueled Unity sessions, you’ll have those tails wagging and those hairstyles bouncing in no time!