What does "Write Defaults" in the animation state inspector actually do?

Question

In my Unity project, I had an issue recently where a tool which autogenerated animation controller layers caused issues with existing layers because it was generating layers with Write Defaults set to OFF, but the existing layers were full of states where it was set to ON.

On talking with others, I gather that mixing these two settings in the same controller causes chaos.

But the thing is, if that were truly the case, the UI would reflect that. It would just be a single checkbox on the entire controller, and I wouldn't be able to set it differently on every single node. Yet I can, so there must be a use case for mixing them.

Unity defaults this checkbox to ON, suggesting that they recommend that.

VRChat, on the other hand, recommend setting it to OFF.

So I don't know who is right on this but it creates an annoying situation where if I want to follow VRChat's recommendations I have to manually uncheck a checkbox on every single animator node, which isn't great UX.

So what I'm wondering is, exactly what does this checkbox do that makes a mix of the two settings break stuff, while setting everything to OFF or everything to ON apparently works fine together. Does it exist solely to torment new developers who don't expect that the editor has extreme quirks?

Answer 1

This is one of those questions you can answer with a search.

For me, the third result is the official documentation, stating:

Write Defaults: Whether or not the AnimatorStates writes back the default values for properties that are not animated by its Motion.

And the second result is this thread including a quotation from a Unity developer about why they chose to default it to ON:

In 5.0 we have added a property on the State to "Write back default values". Meaning that if turned on, it will write back the default values of all animated properties ( on a Controller wide-basis) that are not animated in that State.

By default, its "on", so we don't change the behavior that we had before.

So if you want the non-animated properties of a State to keep the value it had previously, simply turn it off.

So it looks like the default ON was chosen for backward compatibility with versions before 5.0, so as to not break pre-5.0 assets/projects that relied on this behaviour, not because they recommend it be left ON in every project. (If it were meant to always be left on, they would not have added the option to turn it off!)

If compatibility with VR Chat is important to your project today, then follow VR Chat's current recommendations, not a backward compatibility concession that was made for an ancient version of the engine from half a decade ago.

Answer 2

As the documentation says, this setting decides what happens with those values which are not animated by this state, but are animated by another state in the same layer of this animation controller. When you switch it on, those values are reset back to the default upon entering this state. When you switch it to off, they retain whatever values they had after exiting the previous state.

Regarding the conflicting recommendations regarding "always on" and "always off": It is perfectly possible to mix both behaviors in the same animation controller, and there certainly are use-cases for it. But for consistency reasons, it can be useful to stick to either one or the other as a default setting. It makes it easier for you to form a mental model regarding how animation state transitions work in your game.