Parameters, sync and memory

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

What a parameter is

A parameter is a named value. A menu control writes it, and the animator layers read it. A toggle writes true or false, an exclusive group writes a whole number, and a radial writes a number with decimals. VRChat calls these types Bool, Int and Float.

Some parameters are synced: VRChat sends them to the other players, so they see the toggle change. VRChat gives an avatar 256 bits of memory for synced parameters. A parameter can also be saved, which keeps its value between avatar loads. Saving costs 0 bits: only synced parameters count.

What costs bits

Parameter	Bits
A synced Bool, such as a toggle	1
A synced Int or Float, such as an exclusive group or a radial	8
A parameter that is not synced	0

Two choices in AvatarDoc follow from this table:

An exclusive group is one Int, so it costs 8 bits however many toggles it holds. Ten separate toggles cost 10 bits, and ten toggles in a group cost 8.
A toggle that is not Synced costs nothing, but other players never see it change.

These cost no synced bits at all:

a trigger, an override and a Hold the rest rule, which read what exists or change the animations
a contact receiver or a PhysBone, whose values every player's copy of the avatar works out by itself
the hidden value that a blend shape trigger uses, which stays inside the animator
a preset, which has a parameter of its own that is never synced or saved

Fit in VRChat's parameter memory shows how to save bits. Limits lists the limit.

How AvatarDoc names parameters

An entry with an automatic name gets the component's Parameter prefix, a slash and the entry's name, such as AD/Hat. A slash inside the entry's name becomes an underscore. When another entry or a parameter the avatar already has would get the same name, the second gets a space and a 2, the third a 3, in menu order.

An entry can use a custom name instead. If the avatar already has a parameter of that name, AvatarDoc reuses it. It adds nothing to the avatar's list, takes the type and the settings of the existing parameter, and a note says so. If only an animator has the name, AvatarDoc binds to it and adds no parameter to the Expression Parameters. If the name is new, AvatarDoc picks its type from the values that use it: a Bool for the value 1, an Int for another whole number, a Float for a number with decimals. Several controls on one new name widen the type as far as needed.

A control whose value the existing type cannot hold, such as a radial on an Int, is an error.

Several components on one avatar

An avatar often has more than one AvatarDoc component: its own on the root, and one in each prefab with a menu of its own. Each component names its automatic parameters with its own prefix, and an exclusive group's parameter takes the prefix of the component the group belongs to.

VRChat saves a value under its parameter's name. If two components both made AD/Hat, the build would call the second one AD/Hat 2, in menu order. Adding, removing or moving a component would then change which toggle gets which name, and a saved value would show up on the wrong toggle. That is why a new component takes its prefix from its object's name, such as CatEars, when it is not on the avatar's root, and why the prefix never follows a later rename: the names stay readable and stay the same. Modular Avatar keeps names apart by adding a code made from where the object sits, which never clashes but makes names you cannot read, and those change when the object moves.

When two components would still make the same automatic names, such as two copies of one prefab, or a prefab made with an earlier version on AD beside the avatar's own AD, the inspector warns before upload and offers Give this component its own prefix. Parameter prefix explains the rule. Custom names are different: two components may use the same custom name on purpose, to share one parameter, and the toggle's parameter row then says who else uses it.

The order of the parameters

At upload, AvatarDoc copies the avatar's Expression Parameters asset and adds the new parameters at the end of the copy, in menu order. Your own asset is not changed.

VRChat syncs parameters by their place in the list, not by their name. A PC version and a Quest version of one avatar must therefore have the same list, or one platform shows the other platform's players the wrong toggles.

This is why the Platform setting of an entry does not remove its parameter. On the other platform, the entry builds no menu control and no layers, but its parameter stays in the list, in the same place. AvatarDoc also compares the list with another copy of the same avatar when that copy is open in a scene with the same blueprint id, and warns at the first place where the two differ. Different setups for PC and Quest shows the settings.

The memory check

Before it builds, AvatarDoc adds the bits of the avatar's existing synced parameters to the bits of the parameters it is about to add. It takes away the bits that your removals free. The memory bar in the inspector shows the same count.

If the total is more than 256, the build stops with an error. When VRCFury is installed, the same check is a warning instead, because VRCFury makes the parameters smaller at upload until they fit. The message says how many bits are over.

Removing frees bits

Remove from avatar takes a menu item of the avatar out of the build. AvatarDoc also removes the parameter and the animator layers that nothing else needs, and counts the freed bits. It keeps a parameter that something else still reads, and the inspector names what keeps it. See Remove things from the avatar.

Docs for AvatarDoc 0.7.1