Vtool: Avatar Auto-Fixer Pro

Pre-upload checks and fixes for VRChat avatars in Unity.

Scan your avatar, fix the usual SDK problems, shrink textures, then upload like normal.

Important

Please make sure to read the Important section before using Fix All / Auto Fix. Prefer Individual fixes.

Overview

Vtool is a Unity Editor window for VRChat avatar creators. Point it at your avatar root and it tells you what is wrong before you upload.

Where	Unity Editor only
Install	VRChat Creator Companion (VCC)
Price	Free
Code	Open source on this repo
Languages	English, Arabic, Spanish (bilingual labels)

Languages and help

Pick a language in the window header. Non-English UI shows bilingual labels like فحص (Check). VRChat terms such as PhysBones, PipelineManager, and Quest stay in English.

Hover buttons for tooltips. Major actions also show a short caption explaining what they do and what they will not delete.

The 3 tabs

Check Blockers, warnings, and a performance snapshot. Poly count, textures, VRChat setup, PhysBones, audio, Quest shaders, and more.

Fix Safe one-click fixes. No mesh or object removal. Scripts, materials, bounds, audio, lip sync, view position, PipelineManager.

Textures Lower import size or prep for Quest. Cap to 512 / 1024 / 2048, restore originals, convert mobile shaders.

Install

Requirements: Unity 2022.3+, VRChat Avatars SDK, VCC

Step 1. VCC → Settings → Packages → Add Repository

https://raw.githubusercontent.com/DARKSIDE957/Vtool/main/index.json

Step 2. Open your project in VCC → Manage Project → add Vtool Avatar Auto-Fixer Pro

Step 3. In Unity: Vtool → Avatar Auto-Fixer Pro

Tip

You can update while Unity is open. If the window looks old after an update, use Vtool → Apply Package Update (Reload).

Quick start

1. Drop your avatar root into the tool (or Auto-Detect)
2. Check tab: read what failed
3. Backup Avatar or rely on auto rollback before fixes
4. Fix tab: Fix All Safe Upload Errors
5. If anything breaks: Rollback Avatar
6. Textures tab: only if you need smaller textures or Quest shaders
7. Upload through the VRChat SDK

What gets checked

Upload blockers

• Missing VRCAvatarDescriptor or PipelineManager
• Missing humanoid Animator
• Missing scripts
• Null material slots
• Broken shaders (pink materials)
• Missing meshes
• Extreme polygon count
• Over 256 PhysBone components (VRChat hard limit)

Warnings

• View position / lip sync not set
• Chest bone not mapped
• Bad root or negative scale
• High poly count, materials, PhysBones, particles
• 4K / 2K+ textures, missing mipmaps
• Audio not 3D, too loud, play on awake
• Other avatars active in scene
• Non-Quest shaders

What Fix All changes

Fix All is conservative. It does not delete meshes, GameObjects, or material slots. It also never removes anything on the head, face, or hair.

• Fills null material slots using a nearby material on the same renderer
• Adds PipelineManager if missing
• Fixes skinned mesh bounds
• Fixes audio (3D, volume, play on awake)
• Sets view position only if empty
• Sets lip sync only if empty

Missing scripts and excess PhysBones (scripts only — never GameObjects/meshes, and never on head/face/hair), mipmaps, scene avatars, and placeholder materials are under Individual fixes with a confirmation dialog.

Pink shaders still need manual reassignment.

Safety

Warning

Vtool saves a rollback copy before fixes. If something looks wrong, click Rollback Avatar in the Fix tab.

Vtool will not delete GameObjects, meshes, or the head/face/hair region. PhysBone reduction and missing-script cleanup skip that area on purpose.

You can also use Backup Avatar for a visible copy in the scene, or Unity Ctrl+Z for the last edit.

Test on a copy of your project if you are unsure.

Known issue: head disappearing

Important

Some users still report the avatar head / face disappearing after clicking Fix (reported on bases like Manuka / Powari, whose head mesh is often named *_atama). I am still investigating and hardening head/face/hair protection (latest work in v2.3.0+).

It is okay to use the tool. Prefer Individual fixes for only what you need. Do not always use Fix All / Auto Fix.

Suggested flow: Check → Backup Avatar → run one Individual fix at a time.

If the head disappears:

1. Click Rollback Avatar immediately (or Unity Ctrl+Z)
2. Note which Fix button you used (Fix All, Reduce PhysBones, Remove missing scripts, etc.)
3. Use Check → Copy Error Codes and open an issue with that report + avatar setup notes

Links

• Releases
• Report a bug
• Buy Me a Coffee (optional)

_{by DARKSIDE957}