Layers, Write Defaults and pinned layers

هذا المحتوى غير متوفر بلغتك بعد.

You do not need this to use AvatarDoc; it explains why it behaves as it does.

Layers

The FX animator of an avatar is a list of layers. Each layer has states, and each state plays an animation that sets objects, blend shapes and materials. The layers play together. When two of them set the same thing, the layer that sits later in the list decides it. AvatarDoc builds its layers with this in mind.

Every toggle, radial, exclusive group and condition trigger gets its layers from AvatarDoc, named AD: and the entry's name. The other layers add a word in brackets after the name, such as (preset), (shape), (flip), (distance) or (pin), and a layer that follows a shape has its own name. A merged animator keeps the layer names of its own controller. Limits counts the layers.

The order of the layers

When the build is finished, the layers of the FX controller stand in this order, from first to last:

the avatar's own FX layers
AvatarDoc's toggle and condition trigger layers, with the toggles, exclusive groups and radials in menu order
AvatarDoc's preset, touch and follow layers
the merged animators, both AvatarDoc's own and Modular Avatar's
the Fade and blend shape trigger layers, and after them all the pin layers

Layers that VRCFury adds land before the last step too. AvatarDoc moves the pin layers to the end only in its last pass, after every other tool has run. See Pin layers go last.

An ordinary layer is simple:

A toggle's layer has an off state and an on state. The animation of each state sets every target of the toggle. The on state sets the on values. The off state sets the values the targets have in your scene, or the off value you chose.
An exclusive group has one layer with an off state and one state for each toggle. A state sets its own toggle's targets on and the targets of the other toggles off.
A radial has one state that blends between the value at the low end and the value at the high end.

Write Defaults

Write Defaults is a setting of each animator state. When it is on, the state sets everything that its layer ever animates back to its starting value, unless the state sets it itself. When it is off, the state sets only what its own animation sets.

AvatarDoc chooses one setting for all its ordinary layers, so that they match the rest of your avatar:

It reads the states of the avatar's own FX layers. When every state agrees, AvatarDoc uses that setting.
When they disagree, or when there are no states, AvatarDoc uses Write Defaults on. A warning names the layers that mix the two settings, and the header of the inspector shows what AvatarDoc uses.
It does not count additive layers, layers that are one state holding a blend tree, or its own pin layers.

A merged animator keeps the Write Defaults of its own controller, unless Match write defaults is on, which it is by default. Then its layers follow the avatar's setting. An additive layer, and a layer that is one state holding a direct blend tree, keep Write Defaults on either way, because they stop working without it.

Pin layers

Some layers must not use Write Defaults. These are the pin layers:

the second layer of a toggle or a trigger that holds a shape with Pin, or with a Hold the rest rule
the layer of a blend shape trigger
the layer of a touch trigger in Fade mode
the shared layers that pause blinking and lip sync

The second layer of a toggle or a trigger is named like its main layer, with (pin) after it. The pause layers are named AD: Blink pause and AD: Lip sync pause. Every state of a pin layer has Write Defaults off, whatever the rest of the avatar uses.

Why Write Defaults is off

A pin layer sits last in the list (see The order of the layers), so it wins over face tracking and gestures while its entry is on. When the entry is off, the layer must let go. With Write Defaults on, its off state would write the starting value of the shape on every frame, from the last layer, and freeze face tracking and blinking on that value. With Write Defaults off, a state writes only what it has a curve for. The off state of a pin layer has no curve for any shape the layer holds, so while the entry is off those shapes are free for face tracking, blinking, gestures and your other toggles.

Explicit rests

A layer that stops writing a shape leaves it at the last value it was given. A pinned smile would stay when the toggle goes off, if nothing else moved the shape.

So a pin layer resets once, then lets go. On its way from on to off, it passes a short state named Reset. Reset plays for a moment, 1/60 of a second (one frame at 60 frames a second, a few at higher frame rates), and sets each shape the layer held back to its rest: the value it has in your scene, or the row's off value when it has one. Then the layer moves on to its off state, which writes nothing for those shapes. From then on, whatever else moves a shape decides it: face tracking, blinking, a gesture or another toggle. A shape that nothing else moves stays at its rest.

The layer also resets once when the avatar loads: it starts in a state named Load, which plays the same moment of rest and passes on to Reset. So the avatar loads with these shapes at rest, even when AvatarDoc wrote a default into the avatar itself, such as the pose of an exclusive group's default member, and the saved choice is another member.

At the very end of the build, when every layer from every tool is in the controller, AvatarDoc decides what each Reset sets. For each shape and each material property that a pin layer writes, it asks whether another layer owns it. Another layer owns it when it is not additive, its weight is higher than 0, no animator layer control can fade it, and one of these is true:

every state of the layer has Write Defaults on, and the layer animates the shape somewhere
every animation the layer can play has a curve for the shape
a direct blend tree of the layer has a child with a curve for the shape, which is how face tracking is built

If another layer owns the shape, Reset leaves it out too, and that layer decides from the first frame. If no layer owns it, Reset sets it back to its rest. This guess can be wrong on a real avatar: face tracking that another layer can fade, or a blink loop that rests in an empty state, does not count as an owner. A wrong guess costs that moment at most, because Reset and Load are the only states that write the rest value, and only at load and on the way out. A layer whose Reset has nothing to set has neither state, and goes straight from on to off.

The same rule hands back the material properties that a Hold trigger or a Fade trigger changes. On an avatar with Write Defaults off, the layer of a Hold trigger that changes a property passes a Reset state too. On an avatar with Write Defaults on, that layer's off state writes the property on every frame anyway, so it holds the property at rest the whole time the trigger does not fire.

Off values

A row's own off value, set with Set a value when off, is its rest. A toggle's layer holds it the whole time the toggle is off, and so does a Hold trigger's layer for a blend shape row. A trigger in Fade mode, a blend shape trigger, and a Hold trigger's property row on an avatar with Write Defaults off set it when the avatar loads and every time the effect ends; while the trigger rests, the value stays unless something else moves it. On an avatar with Write Defaults on, a Hold trigger's layer holds a property's off value the whole time it rests.

Two details:

When several layers hold one shape, each of them resets it once on its own way out, so the shape goes back to rest whichever of them turns off last. While a lower layer still holds the shape, an upper layer that turns off covers it for that moment only. When two layers rest one property at different off values, the value after both are off is the one of the layer that turned off last, and at load the one of the later layer.
An exclusive group goes from one member to the next through Reset and its off state, so each member state sets only its own shapes. Switching members takes a frame or two.

A shape that VRChat blinks or speaks with is never handed back to rest, not even for the moment of Reset. See Blinking, lip sync and face tracking.

Pin layers go last

AvatarDoc builds its layers before Modular Avatar and VRCFury run. A layer that they add later would take a shape back from a pin layer. So AvatarDoc gives each pin layer the highest priority, and in its last pass it moves every pin layer to the end of the FX controller. It moves only the layers it made itself, found by their exact names. It also points a layer control of another controller at the same layer as before, because such a control names a layer by its place in the list.

VRCFury has a Write Defaults fixer that can turn Write Defaults on for every layer. In its last pass, AvatarDoc turns it off again for its own pin layers. This is why the page about VRCFury and Modular Avatar says to choose Skip in the fixer.

Hold the rest keeps only what is needed

A Hold the rest rule starts by writing every other shape of the mesh. A face can have hundreds of shapes, and most of them never move. In its last pass, once every tool has added its layers, AvatarDoc removes the curves of the shapes that nothing moves, because those shapes already show the value the rule would hold them at. It keeps a curve when:

an animation of any controller of the avatar moves the shape, or an override pins it
the rule holds at 0 a shape that is not at 0 in your scene
the shape is one that VRChat blinks or speaks with, and the rule's switch for it is on

A note says how many shapes the rule holds in the end. The note in the inspector says "up to" for this reason. A shape that only something outside the avatar moves, such as a dance in an MMD world, is not held. Hold the rest of a face shows the controls.

When two pieces hold one shape

AvatarDoc Shapes writes into animations that other layers play. When two pieces hold one shape and different layers switch them, the later layer decides the shape, because of the rule at the top of this page. A warning names the pair. Put both pieces on one toggle or in one exclusive group to avoid it.

Docs for AvatarDoc 0.7.1