Av3Emulator runs VRChat's avatar animator inside the Unity editor

A PlayableGraph re-implementation of the avatar runtime

Av3Emulator is an emulator for VRChat's Avatars 3.0 system, built on the Unity PlayableGraph API. The README is specific about the two pieces it leans on, the AnimationControllerPlayable and the AnimationLayerMixerPlayable, and says the whole thing is a reimplementation done in the Unity editor rather than a copy of the in-game runtime.

That distinction is the project's value. Avatars 3.0 is a layered animator with expression parameters, custom menus, gesture weights and visemes, and testing any of it normally means uploading an avatar and running it in game. Av3Emulator lets you drive those behaviours in the editor, on the animator you already have open.

The package metadata gives the practical constraints. The package is named `lyuma.av3emulator`, the display name is Av3Emulator, the version is 3.4.14, and the type is `tool`. The Unity version is 2019.4, and there is a VPM dependency on `com.vrchat.avatars` at `^3.1.0`, so the VRChat avatar package has to be present. The licence field in the package manifest says MIT, while the repository metadata classifies the licence as one GitHub cannot categorise, with the text in `LICENSE.txt`.

The releases tell you what is changing. v3.4.14 is an updated SDK, v3.4.13 fixed VRCRaycast and GestureManager errors, and v3.4.12 added VRCRaycast and VRCPlayAudio support, so the recent work has been about keeping up with the VRChat SDK rather than adding features.

Adding the emulator to a scene

The README's first instruction is a download, pointing at the latest version on the GitHub releases page, and then the setup is a menu action.

Go to the Tools menu and select Avatar 3.0 Emulator. That adds an object to your scene, and the README is careful to say you can always remove it if you do not want it to run. The object is where you set the default VR mode, the tracking type, or the Animator to Debug setting.

The second surface is the component on the avatar itself. To emulate walking and movement you click the avatar and scroll down the inspector to the bottom section with the Lyuma Av3 Runtime component, where the README says you can change things.

So there are two control points, one scene level object that decides the mode and one avatar level component that drives the runtime, and both are in the editor rather than in a build. For a team shipping avatars, the practical benefit is iteration speed: a parameter change is a slider move rather than a rebuild and an upload.

The README also lists what it does not do. A custom inspector is not implemented, visualisation of IK tracking state when a limb is not in animation mode is not implemented, eye tracking and blinking support is not implemented, and set view position is not fully implemented.

Debugging the animator live in the editor

The feature that makes this more than a test harness is live viewing and editing inside Unity's Animator window. You pick the controller with the Animator To Debug dropdown, and from there you can change parameters from inside the controller, for example moving the red dot in the 2D blend tree for Standing, crouching or going prone with the Upright slider, or testing Sitting or AFK. To emulate walking you can select the Base layer, open the locomotion controller with the avatar selected, and drag around the red dot in the Standing blend tree.

The emulator also shows tracking and animation in the inspector, it has gesture left and right weight so you can test analog Fist gesture strength, and it supports custom expression menus and visemes for both parameters and built-in blend shapes, with the caveat that visemes are always set to 0 percent or 100 percent rather than anything in between.

There is a testing feature for networked behaviour too, described as testing non-local syncing by duplicating or by clicking the Create Non Local Clone checkbox, which is the nearest thing here to a second client.

One caveat the README puts in bold is worth repeating, because it is the kind of difference that wastes an afternoon. The avatar behaves correctly when Animator to Debug is set to Base. When you pick another layer, for example FX, the output of the animator may differ slightly, because direct blend trees with non-zero initial outputs may produce different results, and the whole playable weight may be forced to 1 on the debugged animator.

Editing expression parameters by hand

Parameters can be reached in four ways, and the README lists them because a beginner will not find all of them. You can use the expression menu under the Lyuma Av3 Menu header, the Parameters tab of the Animator window after selecting your layer as Animator To Debug, the blend tree input, or a Parameter Driver. And for manual control you can alt-click the Floats and Ints sections at the bottom of the Lyuma Av3 Runtime script to expand them all and change the values from there.

That last path matters, because the emulator has to emulate operations whose behaviour in game is not obvious, and the inspector is where you can set the value those operations consume.

The rules for boolean and trigger values that are not set in expression parameters are the straightforward ones. An unsynced boolean Set sets to true if Value is checked, an unsynced boolean Random sets to true if RAND() is less than Chance and false otherwise, and an unsynced boolean Add sets to true if Value is not 0.0 in the debug inspector. An unsynced trigger Set sets unconditionally, an unsynced trigger Random sets if RAND() is less than Chance, and an unsynced trigger Add also sets unconditionally.

The Add operation is worth noting on its own, because the README says it shows up as a blank dropdown and, unlike the inspector, uses the Value field instead of the Chance field, and that there is no point in using Add in this case, so you should just fix it if you see a blank dropdown.

Synced parameters behave differently, and triggers are the trap

For boolean values that are set in expression parameters, the rules diverge, and the README flags the Add operation as the notable difference. A synced boolean Set sets to true if Value is checked, a synced boolean Random sets to true if RAND() is less than Chance and false otherwise, and a synced boolean Add sets to true if Value plus the current value is not 0.0 and false otherwise.

That last rule has a practical consequence the README spells out. Using the Add, the blank dropdown, with a Value of -1.0, whether in the debug inspector or by using Set first, makes it possible to make a toggle operation, but only for boolean values in your expression parameters.

Triggers are where the README stops being calm. It says triggers set in expression parameters act completely unintuitively, and tells you in capitals to avoid using parameter drivers on trigger parameters set in expression parameters. The rules it then gives for synced triggers are that Set uses the Value in the debug inspector and sets to true if it is not 0.0, false if it is 0.0, and does not set the trigger if it is set to 0.0 by the next frame. Random sets if RAND() is less than Chance and false otherwise. Add sets to true if Value plus the current value is not 0.0 and false otherwise, and again does not set the trigger if it is set to 0.0 by the next frame.

One more property closes the section: synced trigger parameters remember if they were set to true, and will only set again if explicitly set to false and then true again.

That memory behaviour is exactly the kind of thing that is invisible until a bug report says the trigger fired when it should not have.

Known issues, Write Defaults, and the SDK's proxy animations

The other known issues section is short and points at two different sources of surprise.

The first is the SDK's own animations. The `proxy_` animations included in the SDK are incomplete, so unless you override them you should not expect your avatar to have a full walking cycle, and it is normal for backflip, `VRCEmote=6`, to stop halfway.

The second is configuration, and it is stated as a hard requirement rather than a tip. If you have unexplained issues they might happen in game too, and the most common cause is Write Defaults being turned on in one or more states, in any layer, in any controller. You must have Write Defaults off everywhere to ensure proper operation 100 percent of the time.

The README also suggests a second tool for when the Animator window is not enough, the PlayableGraph Visualizer, which can be found in the Unity Package Manager under Advanced and Show preview packages. The README's assessment of it is honest, that it is hard to use, but it does a good job of visualising clip, layer and playable weights.

The pattern across all of this is worth naming. Most of what the emulator surfaces is not a bug in the emulator, it is a behaviour of the VRChat animator system that is hard to observe in game. The tool's value is that it makes those behaviours visible while you still have the avatar open.

Editorial conclusion

Adopt Av3Emulator when you build VRChat avatars and want to iterate on animation states, expression parameters and gesture weights without uploading to VRChat for each test. Do not expect it to reproduce the VRChat runtime exactly, since the README lists unimplemented features and documents trigger parameter behaviour that differs from the in-game rules. Verify first that your project uses the Unity version the package targets, 2019.4, that the VRChat Avatars package `com.vrchat.avatars` at `^3.1.0` is installed, that Write Defaults is off in every state, and that the SDK's `proxy_` animations are overridden if you need a complete walking cycle.

Frequently asked questions

Official sources

1. Issues
2. lyuma/Av3Emulator on GitHub
3. README
4. Releases