PhysBones

V · EThis is an official VRChat information page!

It is reviewed and approved by the VRCWiki Team. Learn how to contribute to this page by reading the Contribution Guide.

V · EThis page is a stub.

You can help the VRChat Wiki by improving it.
[Reason: Please expand and proofread, in reference to the Manual of Style. Add info about support in worlds.]

PhysBones (a pormanteau of "physics bones") are components, native to the VRChat SDK that allow avatars to display additional motion beyond the normal skeletal movements. PhysBones were implemented into VRChat on April 21, 2022.

Overview

PhysBones are designed to be a more performant, and free replacement for Dynamic Bones, which are a paid Unity asset. These can be enabled on components like hair, clothing, tails, ears, and more, allowing those features to be affected by movement, gravity, and collisions. With the Avatar Dynamics system, PhysBones can optionally be used as interactions by oneself, or other users, for interactions such as grabbing and posing.

History

Before PhysBones, VRChat added support for Dynamic Bones circa 2017. PhysBones was first introduced as "physics bones" in the April 2021 Developer Stream, during the Avatar Dynamics segment. An update about its development was posted on Medium on December 17, 2021. After the season, Avatar Dynamics launched into Open Beta on March 4, 2022. The Open Beta period ended on April 21, 2022, and subsequently was launched to VRChat's live build on the same day, in the VRChat 2022.1.2 (build 1189) release.

As an expansion to PhysBones, the introduction of SquishyBones was added in 2023.2.2 (build 1304) on May 3, 2023.

Initially, Dynamic Bones were still supported, and even had a user option to be automatically converted into PhysBones, but as of the VRChat 2024.3.1 release, Dynamic Bones are now always automatically converted. VRChat SDK changes were made, so that compatibility with uploading new avatars with Dynamic Bones components are no longer permitted.

SDK

Components for PhysBones, and SquishyBones can be found in the VRChat SDK, and be applied to avatars within avatar projects on Unity, and limited forms of PhysBones in world projects.

Avatar SDK

Version 1.1 - Options

Option	Values	Description
Root Transform	(Armature component on avatar)	The transform where this component begins. If left blank, we assume we start at this game object.
Ignore Transforms Size	Integer value 0-99, adds an "Element" which you apply an armature component	List of ignored transforms that shouldn't be affected by this component. Ingnored transforms automatically include anty of that transform's children.
Ignore Other PhysBones	On/Off	When enabled, automatically ignore transforms targeted by another PhysBone component. These are determined at initialization and regardless if the components are enabled or disabled.
Endpoint position	X value, Y value, Z value	Vector used to create additional bones at each endpoint of the chain. Only used if the value is non-zero.
Multi Child Type	Ignore, First, Average	Determines how transforms with multiple children are handled. By default those transforms are ignored.
Forces - Integration Type	Simplified, Advanced	Determines how forces are applied. Certain kinds of motion may require using a specific integration type.
Forces - Pull	0.000-1.000	Amount of force used to return bones to their rest position.
Forces - Spring (Simplified)	0.000-1.000	Amount bones will wobble when trying to reach their rest position.
Forces - Momentum (Advanced)	0.000-1.000	Amount bones will wobble when trying to reach their rest position.
Forces - Stiffness (Advanced)	0.000-1.000	Amount bones will try and stay at their current orientation.
Forces - Gravity	0.000-1.000	Amount of gravity applied to bones. Positive value pulls bones down, negative pulls upwards.
Forces - Gravity Falloff	0.000-1.000	Reduces gravity while bones are at their rest orientation. Gravity will increase as bones rotate away from their rest orientation, reaching full gravity at 90 degress [sic] from rest.
Forces - Immobile Type	All Motion, Worlds (Experimental)	Determines for immobile is calculated. All Motion - Reduces any motion as calculated from the root transform's parent. World - Reduces positional movement from locomotion, any movement due to animations or IK still affect bones normally.
Forces - Immobile	0.000-1.000	Reduces the effect movement has on bones. The greater the value the less motion affects the chain as determined by the Immobile Type.
Limits - Limit Type	None, Angle, Hinge, Polar	Type of angular limit applied to each bone.
Max Angle (Angle, Hinge)	0.0-180.0	Maximum angle each bone can rotate from its rest position.
Max Pitch (Polar)	0.0-180.0	Maximum angle each bone can rotate from its rest position.
Max Yaw (Polar)	0.0-90.0	Maximum angle each bone can rotate from its rest position.
Rotation	Pitch: 0.000-360.000, Roll: 0.000-360.000, Yaw: 0.000-360.000	Rotation of angle
Collision - Radius	0.000-9,999,999.000	Collision radius around each bone. Used for both collision and grabbing.
Allow Collision	True, False, Other	Allows collision with colliders other than the ones specified on this component. Currently the only other colliders are each player's hand as defined by their avatar.
Allow Self (Other)	On/Off	Allow collision for yourself.
Allow Others (Other)	On/Off	Allow collision for other users.
Colliders - Size	0-99, adds an "Element" which you apply a Phys Bone Collider Base component	List of colliders that specifically collide with these bones.
Stretch Motion	0.000-1.000	The amount motion will affect the stretch/squish of the bones. A value of zero means bones will only stretch/squish as a result of grabbing or collisions.
Max Stretch	0.000-9,999,999.000	Maximum amount the bones can stretch. This value is a multiple of the original bone length.
Max Squish	0.000-1.000	Maximum amount the bones can shrink. This value is a multiple of the original bone length.
Allow Grabbing	True, False, Other	Allows players to grab the bones.
Allow Self (Other)	On/Off	Allows yourself to grab your own bones.
Allow Others (Other)	On/Off	Allows other users to grab your bones.
Allow Posing	True, False, Other	Allows players to pose the bones after grabbing.
Allow Self (Other)	On/Off	Allows you to pose your own bones.
Allow Others (Other)	On/Off	Allows other users to pose your bones.
Grab Movement	0.000-1.000	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.
Snap To Hand	On/Off	When a bone is grabbed it will snap to the hand grabbing it.
Parameter	[Parameter name]	Keyname used to provide multiple parameters to the avatar controller
Is Animated	On/Off	Allows bone transforms to be animated. Each frame bone rest position will be updated according to what was animated.
Reset When Animated	On/Off	When this component becomes disabled, the bones will automatially [sic] reset to their default rest position
Show Gizmos	On/Off	N/A
Bone Opacity	0.000-1.000	N/A
Limit Opacity	0.000-1.000	N/A

Version differences

VRChat supports multiple component versions for PhysBones. Existing components stay on the version they were created with until the creator updates them manually in Unity.

• Version 1.0 is the original release.
• Version 1.1 changes how Gravity and Stiffness behave, and adds stretch and squish support often referred to as SquishyBones.

In version 1.0, gravity behaves more like a force that competes with other settings. In version 1.1, gravity and stiffness act more like ratios that influence the final resting result of the chain.

Setup notes

PhysBones require an endpoint to simulate properly. A single transform, or a root with only direct children and no further chain, usually needs a non-zero Endpoint Position or an added end bone to behave as expected.

Creators can also choose between Simplified and Advanced integration types. Simplified exposes Spring, while Advanced exposes Momentum and Stiffness for more detailed tuning.

Avatar parameters

When the Parameter field is set on an avatar PhysBone, VRChat exposes additional Animator parameters using that prefix. These can report whether the chain is grabbed or posed, along with normalized angle, stretch, and squish values. These parameters do not need to be added to the avatar's synced Expression Parameters list.

Performance and limits

On avatars, a single PhysBone component can affect up to 256 transforms. VRChat also notes that Polar limits are more expensive than Angle or Hinge, so simpler limit types are preferred where they achieve the same result.

PhysBone collision and grabbing use a bounding box that is capped at a maximum size. Very large stretching setups can still work visually, but users may not be able to touch or grab bones outside that interaction range.

Avatar performance

PhysBones were introduced to VRChat as an optimized and free alternative to legacy Dynamic Bones for Unity. Compared to Dynamic Bones, more PhysBones can be applied to an avatar on both PC, and Android versions, as they are more cost-performant.

Definitions

Avatar Quality	Quality Description
PhysBones Components	The number of PhysBone components on the avatar.
PhysBones Affected Transforms	The total number of transforms affected by PhysBones components on the avatar.
PhysBones Colliders	The number of PhysBone collider scripts on the avatar.
PhysBones Collision Check Count	The sum of how many PhysBone transforms each collider can affect. This can count transforms twice or more, because a single transform can be affected by multiple colliders.

PC limits

Avatar Quality
PhysBones Components	4	8	16	32
PhysBones Affected Transforms	16	64	128	256
PhysBones Colliders	4	8	16	32
PhysBones Collision Check Count	32	128	256	512

Mobile limits

Avatar Quality
PhysBones Components	0	4	6	8
PhysBones Affected Transforms	0	16	32	64
PhysBones Colliders	0	4	8	16
PhysBones Collision Check Count	0	16	32	64

If the Very Poor value for an avatar is met on mobile, no matter the current "Show Avatar" state of the avatar, all Avatar Dynamics-related components will be removed.

SquishyBones

A graph, demonstrating stretching and squishing of a SquishyBone.

On May 3, 2023, VRChat announced an expanded addition to Physbones 1.1, called SquishyBones, which grant the illusion of a mesh or physbone being stretched or compressed, affecting bone length, compared to being moved around like a standard Physbone.

Patchnotes for this update included the following:

• Squishy Bones update, allowing for bones to squish and length to be affected by motion.
• Gravity now acts as a ratio of how far the bones will rotate when at rest. A positive Pull is required for bones to move in the direction of gravity.
• Stiffness now acts as a ratio which keeps a bone in it's previous orientation.

Debugging

Using the Action Menu, you can use the Avatar Overlay option to show visual representations of both PhysBones and Contacts live in game. These are useful for seeing exactly what is happening, or if objects have been set up properly.

Both PhysBones and Contacts run in the editor as they would in the client. By entering Play mode you are able to simulate these systems and see how your avatar will react without needing to upload your avatar.

Official resources

• "PhysBones" on the VRChat Creation Docs
• "Avatar Performance Ranking System" on the VRChat Creation Docs
• "Debugging Avatar Components" on the VRChat Creation Docs

See also

• Avatars
• Debug Menu