跳转至

title: "Av3Emulator Research Reference" category: "gaming" description: "Comprehensive research on Lyuma's Av3Emulator for VRChat avatar creation — installation, features, conflicts, and usage guide."

Av3Emulator Research Reference

Source

  • GitHub: lyuma/Av3Emulator
  • Latest Release: v3.4.13 (May 2026)
  • Author: Lyuma (xn.lyuma@gmail.com) + community contributors (jellejurre, anatawa12, hai-vr, Dreadrith, etc.)
  • Description: Emulator for VRChat's Avatars 3.0 system, built on Unity's PlayableGraph API
  • Stars: 572, active development, last push May 2026

1) Installation

Av3Emulator is available in VCC's Curated Packages (since v3.2.0, 2022). To install: 1. Open VRChat Creator Companion 2. Go to Manage Project → select your project 3. Click Manage Packages 4. Find Av3Emulator in the curated list under "Community Packages" or "Tools" 5. Click Install

The package name is lyuma.av3emulator, version 3.4.13. VPM dependencies: com.vrchat.avatars ^3.1.0

Option B: Unity Package via .unitypackage

Download the latest .unitypackage from GitHub Releases: - Direct download: lyuma.av3emulator-3.4.13.unitypackage - Import via Unity: Assets → Import Package → Custom Package lyuma.av3emulator-3.4.13.unitypackage - Import via Unity: Assets → Import Package → Custom Package### Option C: Manual VCC via Repository URL Add the VPM repository URL to VCC if not showing in curated list: 1. In VCC, go to Settings → Packages → Add Repository 2. URL: https://packages.vrchat.com/... (check latest docs for VPM listing)

Note: Creator Companion is NOT required — standalone Avatar SDK works too. However, VCC is recommended for SDK management.

2) How It Works — Features

Core Architecture

Re-implements VRChat's Avatar 3.0 system using Unity's native PlayableGraph, AnimatorControllerPlayable, and AnimationLayerMixerPlayable APIs. Runs entirely in the Unity Editor — no upload-to-VRChat needed. AnimationLayerMixerPlayable APIs. Runs entirely in the Unity Editor — no upload-to-VRChat needed.### Key Features | Feature | Details | |---------|---------| | Animator Window Integration | Live viewing + editing of Animator Controller in Unity's Animator window. Select which layer to debug via "Animator To Debug" dropdown. | | Expression Menu Emulation | Full VRCExpressionsMenu support — Buttons, Toggles, SubMenus, Two/Four-Axis Puppets, Radial Puppets rendered as editable buttons in inspector | | Parameter Editing | View and edit all Float, Int, Bool parameters. Multiple access paths: Parameters tab in Animator window, Blend Tree input, Lyuma Av3 Runtime inspector panel, alt-click ▶Floats/▶Ints | | Gesture Testing | Left/Right Gesture weight sliders to test analog Fist gesture strength | | Non-Local Sync Testing | "Create Non Local Clone" checkbox to test network sync behavior (8-bit float quantization) | | Mirror Clone | View mirror reflection effects, test mirror detection | | Walking/Movement | Emulate walking by adjusting Standing blendtree Upright slider, Velocity controls | | Viseme Testing | Test viseme blend shapes (0% or 100% only) | | Eye Tracking + Blinking | v3.4.7+: Eye look and blink implementation; "Have Eyes Follow Mouse" option | | OSC Support | OSC input/output with configuration file generation; external tool control | | PhysBones + Contacts | PhysBone parameter emulation, Contact Receiver/Sender testing | | VRCRaycast | v3.4.12+: VRCRaycast component support | | VRCPlayAudio | v3.4.11+: Audio compo VRCRaycast | v3.4.12+: VRCRaycast component support | | VRCPlayAudio | v3.4.11+: Audio compoVRCRaycast | v3.4.12+: VRCRaycast component support | | VRCPlayAudio | v3.4.11+: Audio component support | | GestureManager Integration | Optional radial menu via GestureManager from VCC | | Parameter Driver | Emulation of VRChat's Parameter Driver state machine behavior | | Preprocess Hooks | "Run Preprocess Avatar Hook" option — runs NDMF/VRCFury build hooks on play | Preprocess Hooks | "Run Preprocess Avatar Hook" option — runs NDMF/VRCFury build hooks on play |### Not Implemented - Custom inspector for the main component - IK Tracking state visualization when limb not in Animation mode - Eye Tracking / Blinking was NOT initially implemented but has been added in v3.4.7+ - Set View position not fully implemented - Safety emulation (toggle features/components)

3) Known Limitations & Conflicts

VRCFury Conflicts

  • VRCFury v1.751.0 NullReferenceException (Issue #147, CLOSED): VRCFury could cause NRE spam making avatar render blank. FIXED in v3.4.5+ via:
  • Initialization moved from Awake() to Start() (Issue #125/#128)
  • Workaround: "Run Preprocess Avatar Hook" runs VRCFury build on play
  • Animator recreation on Start() to prevent baked defaults
  • VRCFury accesses fields via reflection: runtimes, forceActiveRuntimes, scannedAvatars, RestartEmulator — must not rename these
  • Mirror detection breaks when restarting emulator with VRCFury hooks enabled (Issue #177, CLOSED)

NDMF Compatibility

  • Initialization was moved from Awake() to Start() specifically to fix incompatibility with tools applied on IProcessSceneWithReport — which is how NDMF applies modifications
  • Result: Av3Emulator works well with NDMF now. NDMF processes the avatar, then Av3Emulator initializes after
  • Option: LegacyInitializeOnAwake checkbox exists if Start() causes issues (not recommended with VRCFury/NDMF) egacyInitializeOnAwake` checkbox exists if Start() causes issues (not recommended with VRCFury/NDMF)### Unity 2022 Issues
  • Android build failure (Issue #167, CLOSED): v3.4.3 could not build to Android target on Unity 2022.3.22f1. FIXED in v3.4.5 by removing dynamic keyword usage
  • Package unity field in package.json is 2019.4 — works on 2019, 2020, 2021, and 2022
  • Latest SDK 3.x versions supported (compatible with SDK 3.4.x+)

Other Known Issues (Open)

  • GestureManager radial menu less responsive than standalone (Issue #124)
  • PhysBone testing in Game view broken in some versions (Issue #183)
  • Contact sender/receiver parameters not set correctly on play (Issue #43)
  • Sub Menu cap issue (Issue #32)
  • Pose Avatar button does nothing (Issue #181)
  • OSCQuery support not implemented (Issue #200)

Critical: Write Defaults MUST be OFF

This is stated emphatically: "You must have Write Defaults OFF everywhere to ensure proper operation 100% of the time." If you have WD ON in any state in any layer, Av3Emulator will exhibit unexplained issues (which also happen in-game).

4) Step-by-Step: Testing a Toggle-Based Clothing System

This guide assumes you have an avatar with: - A Toggle parameter (e.g., ClothingToggle, type Bool, saved) - An FX Animator Controller with transitions keyed to this Bool - GameObjects (clothing items) toggled on/off via animation ller with transitions keyed to this Bool - GameObjects (clothing items) toggled on/off via animation### Setup 1. Install Av3Emulator via VCC (see Section 1) 2. Open your avatar scene in Unity 3. Menu → Tools → Avatar 3.0 Emulator → adds a [Lyuma Av3Emulator] GameObject to the scene 4. Configure Emulator: - Set "Default Animator to Debug" = FX (or Base depending on your setup) - Check "Run Preprocess Avatar Hook" = ON (so NDMF/VRCFury build runs before emulator) - Set appropriate VR/Desktop tracking type

Testing Your Toggle Clothing System

Method 1: Via Expression Menu Buttons

  1. Enter Play Mode
  2. Select your avatar GameObject in the Hierarchy
  3. In the Inspector, scroll down to the Lyuma Av3 Runtime component
  4. Look for the Lyuma Av3 Menu section — this renders your VRCExpressionsMenu as clickable buttons
  5. Click your Toggle button (e.g., "Shirt", "Pants") to toggle it on/off
  6. Watch the clothing appear/disappear in the Game view (e.g., "Shirt", "Pants") to toggle it on/off
  7. Watch the clothing appear/disappear in the Game view#### Method 2: Via Animator Window
  8. Enter Play Mode
  9. Click your avatar (to select it)
  10. Window → Animation → Animator (open the Animator window)
  11. In the Inspector, set Animator To Debug = the layer where your toggle logic lives (usually FX)
  12. In the Animator window, you'll see the FX controller with states and transitions
  13. Edit parameters directly:
  14. Click the Parameters tab in the Animator window
  15. Find your ClothingToggle Bool parameter
  16. Check/uncheck it to trigger state transitions
  17. Watch transitions play in the Animator window — active states highlight in yellow

Method 3: Via Runtime Inspector (Direct)

  1. Enter Play Mode
  2. Select your avatar, scroll to Lyuma Av3 Runtime component
  3. At the bottom, find the ▶Floats and ▶Bools collapsible sections
  4. Alt-click to expand all
  5. Find your toggle parameter and change its value directly
  6. The avatar should respond immediately

Method 4: Testing Non-Local Sync (Network Emulation)

  1. On the [Lyuma Av3 Emulator] object, check Create Non Local Clone
  2. A duplicate avatar appears offset — this simulates how the avatar looks to other players
  3. The clone has 8-bit quantized floats and sync delay
  4. Toggle your clothing on the main avatar → verify the clone updates correctly loats and sync delay
  5. Toggle your clothing on the main avatar → verify the clone updates correctly### Verifying Animator Transitions
  6. With the avatar selected and Animator window open on the correct layer
  7. Set Animator To Debug = your FX layer
  8. Toggle the parameter using any method above
  9. Observe in the Animator window:
  10. The active state highlights in yellow
  11. Transition arrows animate/glow during blending
  12. The state machine diagram updates in real-time
  13. Check the Game view to confirm the visual result matches your expectation
  14. Test edge cases:
  15. Toggle rapidly to check for flickering or missed transitions
  16. Check all combinations of multi-toggle interactions
  17. Verify transitions complete their blend duration correctly

Best Practices

  • Write Defaults OFF everywhere — this is non-negotiable for Av3Emulator
  • Use Refresh Expression Params button if you modify VRCExpressionParameters while in Play Mode
  • Use Reset Avatar to force-reset the state machine to initial state without restarting Play Mode
  • If the avatar looks wrong, toggle ResetAvatar checkbox to reinitialize
  • Test both VR and Desktop modes via the Emulator settings esetAvatar** checkbox to reinitialize
  • Test both VR and Desktop modes via the Emulator settings### Troubleshooting | Symptom | Likely Cause | Solution | |---------|-------------|----------| | Avatar invisible/blank | VRCFury conflict or Write Defaults | Check WD OFF everywhere; restart emulator | | Parameters show 0 in Animator | Wrong layer selected for debug | Set Animator To Debug to the correct layer | | Menu buttons don't appear | Expression menu/params not set | Check VRCAvatarDescriptor expression settings | | Toggle doesn't respond | Parameter type mismatch | Verify Bool vs Float parameter in Expression Parameters | | Animator transitions not playing | Write Defaults ON in some states | Set WD OFF in ALL animation states | | Avatar clone not sync'ing correctly | Expected behavior for 8-bit quantized floats | Check "locally8bitQuantizedFloats" for local testing | | Error spam in console | Version mismatch or conflicting tool | Update to latest v3.4.13; disable Legacy Awake mode |