VRChat Avatars Skill

Version: 1.0 Stack: VRChat SDK, Unity

VRChat's performance ranking system means avatars ranked "Poor" or "Very Poor" get automatically hidden by most players' safety settings — your carefully crafted avatar becomes an invisible robot silhouette. Too many materials break batching. Too many bones eat CPU. Mixed Write Defaults cause unpredictable animation behavior. And Quest has dramatically stricter limits that require a separate build, not just the same avatar with fewer polygons.

Building within Good rank limits from the start means your avatar is actually seen by other players. The parameter budget and PhysBone limits aren't arbitrary — they're the line between visible and invisible.

Scope and Boundaries

This skill covers:

• Avatar 3.0 setup

• Expression menus and parameters

• Performance optimization

• PhysBones and contacts

• Animator controllers

Defers to other skills:

• unity-csharp : C# patterns and performance optimization

Use this skill when: Building or optimizing VRChat avatars.

Core Principles

• Performance Rank Matters — Poor avatars get blocked.

• Quest Compatibility — Separate build, stricter limits.

• Parameter Budget — 256 bits max for synced parameters.

• PhysBone Limits — More bones = more cost.

• Test on Device — Mirror and performance differ.

Performance Limits

Quest (Target: Good)

Metric Good Medium Poor

Triangles 10,000 15,000 20,000

Materials 1 2 4

Bones 90 150 256

PhysBones 0 6 8

PC (Target: Good)

Metric Good Medium Poor

Triangles 32,000 70,000

Materials 4 8 16

Bones 150 256 400

PhysBones 16 32 64

PhysBone Colliders 8 16 32

Patterns

Hierarchy Structure

Avatar Root ├── Armature │ └── Hips │ ├── Spine → Chest → Neck → Head │ │ ├── Eye_L, Eye_R │ │ └── Hair bones │ ├── Leg_L → Knee → Foot → Toe │ ├── Leg_R → ... │ └── (Shoulder → Arm → Elbow → Hand → Fingers) ├── Body (SkinnedMeshRenderer) ├── Clothes (optional separate mesh) └── Accessories

Parameter Budget (256 bits)

Type Bits Common Uses ───────────────────────────────── Bool 1 Toggles Int 8 Outfit index, state machines Float 8 Blend shapes, radial controls

Example Budget:

• VRCEmote (int) 8 bits
• VRCFaceBlendH (float) 8 bits
• VRCFaceBlendV (float) 8 bits
• Custom toggles ×10 10 bits
• Outfit selector 8 bits
• Remaining 214 bits

Expression Menu Structure

Main Menu ├── Expressions │ ├── Happy │ ├── Sad │ └── Surprised ├── Toggles │ ├── Hat On/Off │ ├── Glasses On/Off │ └── Jacket On/Off ├── Outfits (Radial) │ └── Select 1-4 └── Settings ├── PhysBone Intensity └── Fallback Toggle

Write Defaults Pattern

Choose ONE approach project-wide:

Write Defaults ON:

• Simpler setup
• Properties return to default when state exits
• Can cause conflicts between layers

Write Defaults OFF (Recommended):

• More control
• Must explicitly set all animated properties
• Each state fully defines its output

Anti-Patterns

Anti-Pattern Problem Fix

Too many materials Breaks batching, hurts rank Combine textures, atlas

Mixed Write Defaults Undefined behavior Pick one, be consistent

Unoptimized PhysBones Performance cost Reduce count, simplify chains

No fallback avatar Blocked users see robot Set a performant fallback

Synced parameters for local-only Wastes sync budget Mark local-only correctly

Full body mesh on Quest Triangle count Separate Quest mesh

Checklist

Setup

• Armature follows humanoid structure

• Avatar descriptor configured

• Eye tracking configured (if applicable)

• Visemes configured

• View position set correctly

Performance

• Triangle count within target rank

• Material count minimized (atlasing)

• Bone count within limits

• PhysBones optimized

• Quest version uploaded (if applicable)

Expressions

• Expression menu organized

• Parameters within 256-bit budget

• Write Defaults consistent

• Gesture layer configured

• Toggles tested

Quality

• No clipping in default pose

• PhysBones behave naturally

• Expressions look correct

• Tested in VRChat (not just Unity)

References

• references/avatar3-setup.md — Avatar 3.0 configuration guide

Assets

• assets/avatar-performance-limits.md — Quest and PC performance limits