vrc-avatars（VRC 头像）

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

1. Performance Rank Matters — Poor avatars get blocked.
2. Quest Compatibility — Separate build, stricter limits.
3. Parameter Budget — 256 bits max for synced parameters.
4. PhysBone Limits — More bones = more cost.
5. Test on Device — Mirror and performance differ.

Performance Limits

Quest (Target: Good)

PC (Target: Good)

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

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