Last reviewed 31 Jul 2026

Test VRChat Avatar Dynamics: A Four-Level Workflow

Test Contacts and PhysBones in increasingly realistic environments. Start with static SDK checks, continue in Unity Play mode, run the built avatar in the VRChat client, and finish with an uploaded multi-user test. Each level catches a different class of problem.

Video Companion

Creator: akalink
Video: Avatar Dynamics Tutorial Part 3: How to Test

What Each Level Proves

Level	Environment	Best at finding
1. Static validation	Unity Edit mode and SDK Builder	Missing components, wrong tags, invalid hierarchy, parameter mismatch, warnings, performance
2. Component simulation	Unity Play mode	Contact values, PhysBone movement, Animator transitions, collisions, local logic
3. Client validation	VRChat Build & Test	Real input, menus, mirrors, Avatar Overlay, self interaction, client-only behavior
4. Multi-user validation	Uploaded private avatar in VRChat	Remote rendering, other-player interaction, permissions, synchronization, PC/mobile differences

Passing one level does not prove the next. A receiver can update correctly in Unity but fail when the user disables Avatar Dynamics interactions. A local test avatar can work perfectly while its remote parameter or platform variant remains incorrect.

Prepare a Repeatable Test Case

Before changing the avatar, record the expected result:

Feature:
Input:
Expected local result:
Expected remote result:
Allowed users:
Saved:
Synced:
PC behavior:
Mobile behavior:

For example:

Feature: Hold-to-toggle shoulder badge
Input: Wearer's Hand remains in receiver for full timer
Expected local result: Badge turns on once after the hold
Expected remote result: Other users see the enabled badge
Allowed users: Self only
Saved: Yes
Synced: Yes
Mobile behavior: Menu fallback remains available

This turns “it feels broken” into a specific failed expectation.

Level 1: Static SDK and Hierarchy Validation

Complete the no-runtime checks first.

Contacts

• Sender and receiver tags match exactly, including capitalization.
• Receiver Allow Self, Allow Others, and Local Only match the intended audience.
• Constant and OnEnter receivers target a compatible Bool, Int, or Float.
• Proximity receivers target a Float.
• Receiver shapes do not overlap unintended body-part senders at rest.
• Local-only parameters are not added to Expression Parameters without a reason.

PhysBones

• Root Transform points to the intended non-humanoid chain.
• The chain has usable child bones or an Endpoint Position.
• Collision radius is non-zero where collision or grabbing is required.
• Allow Collision, Allow Grabbing, and Allow Posing match the design.
• Self and other-user filters are intentional.
• Limits and colliders have visible Scene view gizmos.
• Constraints and PhysBones do not affect the same GameObject.

Animator and expressions

• Parameter names and types match between components and the FX Animator.
• Saved and Synced are enabled only for final state that needs them.
• Every Animator state has a valid route out when its input changes.
• Parameter Driver destinations exist and use supported types.
• The Expressions Menu and Parameters assets are assigned on the Avatar Descriptor.

SDK Builder

Open VRChat SDK → Show Control Panel → Builder and review:

• validation errors;
• warnings;
• avatar performance rank;
• PhysBone component, transform, collider, and collision-check counts;
• Contact count;
• selected build platform.

Do not proceed while a validation error blocks the build. Investigate warnings that directly affect the feature or target platform.

Level 2: Unity Play Mode Simulation

VRChat documents that Contacts and PhysBones run in the Editor. Enter Play mode to inspect movement and live parameter values without uploading.

For Animator testing, assign the relevant controller to the avatar's Animator before Play mode. Remove or restore temporary test assignments before building if the Avatar Descriptor normally supplies the playable controller.

Test Contact values

1. Select the Contact Receiver.
2. Move a matching sender through the receiver.
3. Watch the parameter value in the component or Animator.
4. Repeat with a non-matching tag.
5. Test the receiver boundary and resting pose.

Receiver type	Play mode check
Constant	Value remains active only while contact is present
OnEnter	Value pulses when contact begins
Proximity	Float changes through the expected 0–1 range

Test PhysBone motion

Move or rotate the avatar root and inspect:

• rest position;
• Pull, Spring, Stiffness, Gravity, and Immobile response;
• movement limits;
• collision with assigned colliders;
• chain stretch and squish where enabled;
• clipping at extreme poses.

Editor simulation is useful for motion tuning, but it does not replace hand-controller grabbing or another user's permissions.

Test Animator logic

Change the relevant Animator parameters and verify:

• each expected state becomes active;
• cancel transitions work;
• no state dead-ends;
• off states restore all animated properties;
• menu and Contact inputs agree on the final value;
• a saved parameter can enter the matching logic branch.

Level 3: Local Build & Test in VRChat

In the SDK Builder, select Build & Test under offline testing. The avatar appears in the SDK Test Avatars section of the VRChat avatar menu.

After rebuilding, reselect the test avatar and apply it again. The optional --watch-avatars launch option can switch automatically when a new local build appears.

Use this level to test:

• actual VR controller and Desktop input;
• Expressions Menu controls;
• mirrors and first-person visibility;
• self Contacts;
• PhysBone grabbing and posing by the wearer;
• gesture and tracking changes;
• saved/default behavior during avatar reset;
• performance in the VRChat client.

Use Avatar Overlay

Open the Avatar Overlay from the Action Menu to display Contact and PhysBone volumes in VRChat.

Check:

• sender and receiver shapes align with the visible avatar;
• a hand or finger reaches the expected receiver;
• no resting body-part sender remains inside the volume;
• PhysBone radii follow the intended chain;
• colliders and limits explain unexpected clipping or blocking.

The overlay is a diagnostic view. Turn it off after confirming the geometry and repeat the feature as a normal user would experience it.

Level 4: Uploaded Multi-User Validation

Upload the avatar privately, then test with at least one other player. A private avatar can be worn by its owner while other players observe and interact with it.

Assign roles:

Wearer
├── Operates self Contacts and menus
├── Reports local feedback
└── Changes Avatar Dynamics permissions

Observer
├── Checks remote appearance and timing
├── Attempts permitted Contacts and PhysBone grabs
└── Tests blocked interactions

Run the matrix:

Test	Wearer expects	Observer expects
Synced feature toggled	Local feature changes	Same final state appears remotely
Unsynced local preference toggled	Local feature changes	No shared change
Allow Others disabled	No other-player activation	Contact or grab is blocked
Allow Others enabled	Intended interaction occurs	Contact or grab succeeds
Allow Posing disabled	Grab releases normally	Pose cannot remain locked
Interaction permissions disabled	Feature remains stable	Disabled category cannot interact
Avatar changed and restored	Saved values return as configured	Remote state matches after load

Test both friendship/permission states relevant to the feature. Avatar Dynamics permissions can prevent an otherwise correct component from interacting.

Test PC and Mobile Variants

Use the same Expression Parameters asset and compatible parameter ordering/types across PC and mobile variants. VRChat synchronizes cross-platform custom parameters by their position and type rather than parameter name.

For mobile:

1. Review the mobile performance rank and hard limits.
2. Build the mobile variant, not the PC hierarchy.
3. Use the platform's supported Build & Test workflow on real hardware where available.
4. Confirm required Contacts, PhysBones, and Constraints have not been removed.
5. Confirm a menu fallback exists when precise hand interaction is not practical.

VRChat supports Build & Test for Android mobile devices and iOS with their documented device setup. Real-device testing catches input, performance, shader, and platform-removal behavior that a PC-only preview cannot prove.

Regression Checklist

After fixing one Avatar Dynamics feature, retest nearby systems:

• Expressions Menu navigation;
• gesture layers;
• saved outfit and material toggles;
• other Contact Receivers using related tags;
• adjacent PhysBone chains and colliders;
• avatar scaling;
• mirrors and first-person visibility;
• PC and mobile parameter compatibility;
• performance rank.

Keep a short record of the failing level and fix. If the failure returns, start at the last passing level instead of repeating every step blindly.

Four-Level Acceptance Matrix

Feature	Level 1	Level 2	Level 3	Level 4
Contact tags and filters	Inspect settings	Simulate matching and non-matching sender	Confirm actual avatar hand	Confirm other-player permission
Contact parameter	Match name/type	Watch live value	Confirm client reaction	Confirm remote result if synced
PhysBone motion	Inspect root/radius/limits	Tune movement and collisions	Test wearer grab/pose	Test observer grab/pose
Animator output	Inspect states/transitions	Force each parameter path	Use real menu/contact input	Compare remote appearance
Platform support	Review selected platform	Inspect shared hierarchy	Build local target	Test real PC/mobile variants
Performance	Review Builder statistics	Watch Editor stability	Observe client cost	Confirm acceptable experience remotely

Help! The component works in Play mode but not in VRChat.

Use Build & Test and Avatar Overlay to inspect the built avatar. Check real input reach, Avatar Dynamics permissions, playable-controller assignment, and whether the target platform removed the component.

Help! My local test avatar is invisible to the other tester.

That is expected: SDK test avatars are local-only. Upload a private test avatar before validating remote appearance, synchronized parameters, or other-player interactions.

Help! Avatar Overlay shows the receiver in the wrong place.

Check the receiver's Root Transform, local position, rotation, and avatar scale. Place it under the intended moving bone and rebuild before testing again.

Help! Self interaction works but another player cannot activate it.

Check Allow Others on the component and both users' Avatar Dynamics permissions. Verify the other avatar supplies a matching Contact Sender or attempts the correct PhysBone interaction.

Help! The remote feature shows the wrong state.

Confirm the final custom parameter is marked Synced and has the same type and list position on each platform variant. Do not synchronize a temporary Contact input when only the latched result matters.

Help! PhysBones or Contacts disappear on mobile.

Review the mobile avatar's Builder statistics and performance rank. VRChat removes Avatar Dynamics components when the platform hard limit is exceeded, so simplify and rebuild the mobile variant.

Help! A fix broke another toggle or animation.

Run the regression checklist and inspect shared parameters, FX layers, masks, and animated properties. Reusing one parameter or animating the same property on multiple layers commonly couples otherwise separate features.

Official References

• Debugging Avatar Components
• Local Avatar Testing
• Creating Your First Avatar
• VRChat Contacts
• VRChat PhysBones
• Animator Parameters
• Avatar Performance Ranks
• Build and Test for Android Mobile
• Build and Test for iOS

Related Guides

• Contacts and PhysBone Grabbing
• Build a Hold-to-Toggle Contact
• Avatar Creation
• Avatar Optimization Checklist
• Setting Up VRChat Creator Companion
• VRChat Documentation

Topics: VRChat avatars, Avatar Dynamics, testing, Contacts, PhysBones, Build and Test