Write Defaults

Write Defaults is an option on Animator States, and a headache for many Avatar Creators, as they behave in weird and unexpected ways. The expected behaviour is as follows:

The Write Defaults field decides whether or not the changes made with this animation are persistent or not.

If the Write Defaults field is enabled, the animated fields will return to their default state upon leaving the Animator State.

If the Write Defaults field is disabled, the changes will stay.

By default, Unity enables Write Defaults on newly created states, but the sample Animator Controllers VRChat provides are Write Defaults Off.

The default animator state, which defaults to Write Defaults on.

Example:

If you have a hat that is disabled in the hierarchy when starting the upload process (a.k.a. off by default), and you have a Layer that looks like this:

Untitled

In the case of Write Defaults On:

When going to the Hat On state, the hat would toggle on
When going back to the Hat Off state, the hat would toggle off (since that is the default state being written back)

In the case of Write Defaults Off:

When going to the Hat On state, the hat would toggle on
When going to the Hat Off state, the hat would stay toggled on (since you’re not explicitly toggling it back off or writing back the default)

Guidelines

There are a few guidelines to follow when using Write Defaults Off. Afterwards I will explain why these guidelines exist, just for completeness’ sake:

Don’t mix Write Defaults in a single controller. Mixed Write Defaults will behave like WD off.
- The exception to this is layers with a single state in them. These can, and in the case of Direct Blend Trees, should be set to Write Defaults On.
- It is okay to do this since they never leave their state, and therefore, we never rely on the WD On behaviour.
Don’t use Write Defaults Off on Direct Blend Trees
If you are using Write Defaults Off, all your states should have an Animation Clip or a Blend Tree in them. This Animation Clip can be empty, but it is generally recommended to use an Animation Clip that animates a GameObject that does not exist for two frames (sometimes called a buffer clip).
Note that animating a Transform animation with Write Defaults Off overrides all other animated Transforms from other playing Animator Controllers. This specifically means that, for VRChat, if you are animating any Transform in the FX Layer, it will overwrite all Transforms in the Gesture layer, unless you apply an Avatar Mask that enables only the animated Transforms and disables all others, and apply this mask to your FX Layer Animation Layer. More information about Masking can be found at the Avatar Masks page.

<aside> ⚠️ If you have to use masks due to WD off Transform animations in both your Gesture and FX layers, you can’t use matswaps on any slot but the first one, since a masked transform (whether it’s masked on or off) can’t have animated matswaps apart from the first material slot.

</aside>

<aside> 💡 A useful tool to check if you are breaking these rules (at least the first and third rule) is the VRLabs’ Avatar 3.0 Manager.

In the Write Defaults tab of this tool, it will tell you if you have mixed Write Defaults and set them for you if you press the corresponding button. Do note that it doesn’t make an exception for Direct Blend Trees, so their animator state has to have (WD On) in its name to mark it as Write Defaults On.

</aside>

An example Animation Clip to ensure no empty States remain.