Write Default Bugs in Unity
Write Defaults causes tons of undocumented unity bugs, many of which are still being discovered to this day. These are the bugs we are currently aware of:
Mixed Write Defaults
- Controller contains a mix of WD on or WD off
- A WD Off state is in a layer or beneath a layer containing a WD On state
- Random properties in the controller will "stick," refusing to change even when they are instructed to by an animation.
- Do not mix WD within a controller (except for direct blendtrees and additive layers, where WD MUST ALWAYS be on)
- If a mix is absolutely required, ensure that all WD on is below any WD off
- Note that ALL playable layer controllers in a vrchat avatar are considered one "controller"
Direct Blendtrees and Additive Layers with WD Off
- A state containing a direct blendtree, or a state within an Additive layer, are set to WD off
- Random properties in the controller may grow or shink in value every frame, causing them to fly off into oblivion.
- Blendshapes animated in the controller may have their values unexpectedly multiplied by 2x or 3x.
- Ensure all Direct Blendtrees and all states within Additive layers are always WD on
Transforms in Unmasked Controllers with WD Off
- Multiple controllers in a mixer use WD off (such as Gesture and FX)
- The lowest controller in the mixer (usually FX) will claim ownership of all unmasked transforms
- Even if the transforms are not animated within any state in the controller, it will still prevent any higher controller in the mixer from animating them.
- Use WD on
- Combine Gesture and FX, so that FX claiming all transforms is acceptable (as all transform animations will be within the one controller)
- Add masks to FX, preventing it from owning specific transforms (impossible in some scenarios due to
Broken Properties in Masked Layers)
Muscles in Unmasked Controllers with WD Off OR On
- Multiple controllers in a mixer animate the same humanoid muscle
- The lowest controller in the mixer (usually FX) will claim ownership of all unmasked muscles
- Even if the muscles are not animated within any state in the controller, it will still prevent any higher controller in the mixer from animating them.
- Ensure each muscle is only animated by one controller
- If overriding is required, use Playable Layer Control to weight the override controller to 0 when the animation is complete (like is done with Action)
Muscles in Unmasked Layers with WD Off
- Multiple layers in a single controller use WD off
- Two layers animate the same muscle of the humanoid rig
- The lowest layer "claims" ownership of the muscle the first time it is animated, preventing any higher layer from ever animating that muscle
- Moving to a state no longer animating the muscle does not release ownership
- Use WD on
- Use Animator Layer Control to "weight" the lower layer to 0
Broken Properties in Masked Layers
- A state's layer, or the controller's base layer, contains a mask that does not allow All Transforms
- The state cannot perform a material swap on material slot 0 if it's not an allowed transform in the mask
- The state cannot perform a material swap on a material slot greater than 0 at all
- The state cannot animate properties on a VRC Physbone (and possibly other non-standard component types)
- Do not use masks on the layer or the controller's base layer
Empty Animations with WD Off
- A state uses WD off
- The state contains a "none" animation, or an empty animation clip, in the root motion or any blendtree child
- Similar symptoms to
- If a state uses WD off, ensure that all motions and blendtree children are set to an animation clip containing at least one property (it does not have to be valid)
WD On Blending is not Additive
- WD is on
- A property is set in a clip in one layer
- The same property is modified at a partial weight >0 within a blendtree in a lower layer
- The value of the final property does not account for the value in the first layer.
- For example:
- If the default (resting state) value of the property is 0
- and the property is animated to 5 in layer 1
- and the property is animated to 10 with 0.1 weight in layer 2
- The final value will be 1 (disregarding the 5 entirely)
- However, if the weight on layer 2 is changed to 0, suddenly the final value is 5
- Do not animate the same property from multiple layers if they involve "open-ended" blending.
- All blendtrees involving properties animated in higher layers should fully animate all shared properties in all children.
- Direct blendtrees involving properties animated in higher layers should always have weight 1 (fully animated) or 0 (fall through to above layer).
WD On breaks transition time to blendtrees when a parameter is Animated
- WD is on
- Any parameter in the animator is controlled by an animation
- One state transitions to another state that uses a blend tree, and the current blend involves more than one motion
- The transition ignores the state that is being transitioned from, snapping to the new state immediately
- Use WD off
- Avoid this scenario entirely (do not use blendtrees in a multi-state layer)
- Do not use animated parameters (often unavoidable)