unity-vrc-world-sdk-3

VRChat World SDK 3 Guide

Table of Contents

---

Common Mistakes (NEVER List)

These cause silent world failures, performance disasters, or Quest incompatibility:

Reference Loading Guide

Load only what the task requires.

Before Starting a New World — Design Decisions

These decisions shape every downstream choice. Make them first, before placing any component.

---

Design Philosophy: Quest First

Build for Quest and get PC for free. Build for PC and Quest becomes a separate project.

Quest (Meta Quest 2/3/Pro) defines the performance budget:

• CPU/GPU: ~2× slower than PC VR; tile-based GPU with no hardware shadow maps
• VRAM: ~4 GB shared with OS (vs 6–12 GB on PC); no HDR framebuffer
• Thermal throttling: Sustained 100% GPU load causes clock reduction within minutes

If a world runs at 72 FPS on Quest with a single test client, it will typically run at 90+ FPS on PC — though results vary by shader complexity, CPU-bound workloads, and hardware differences. The converse rarely holds. Verify against the official VRChat optimization documentation before publishing.

NEVER optimize exclusively for PC with "Quest support added later" — by that point, lighting, materials, and mesh density are all locked to PC quality, and the Quest port requires rebuilding everything.

Quest First Cascade — when Quest is required, every downstream decision inherits constraints:

Quest required? → Yes
  ├── Shaders: Mobile-only (Standard Lite, Toon Lit)
  ├── Lighting: Fully baked (no realtime shadows)
  ├── Geometry: 50K-100K triangles (target range)
  ├── Materials: < 25 unique materials
  ├── Audio: Mono, compressed, limited concurrent sources
  └── Physics: Simplified colliders, minimal Rigidbodies

SDK Versions

Supported versions: SDK 3.7.1 - 3.10.4

Important: SDK versions below 3.9.0 are deprecated as of December 2, 2025. New world uploads are no longer possible with these versions.

---

Scene Setup

VRC_SceneDescriptor (Required)

Exactly one is required in every VRChat world.

[VRCWorld Prefab]
├── VRC_SceneDescriptor (Required)
├── VRC_PipelineManager (Auto-added)
├── VRCWorldSettings (Optional - movement speed settings)
└── AvatarScalingSettings (Optional - avatar scale limits)

All Properties

Reference Camera Usage

// Usage:
// 1. Adjust Near/Far clipping (recommended for VR: 0.01 ~ 1000)
// 2. Apply Post Processing effects
// 3. Set background color

// ⚠️ MUST disable the Camera component after configuring — an active Reference Camera
//    renders a second viewport. VRChat reads only the camera settings, not its output.
// Assign the configured (disabled) Camera to VRC_SceneDescriptor > Reference Camera.

Spawn Points Setup

// Spawn points are empty GameObjects assigned to VRC_SceneDescriptor > Spawns array.
// Players enter facing the Z+ direction of the spawn Transform.

// VRChat-specific requirements:
// - At least 2-3 spawn points (for simultaneous joins — single spawn causes overlap)
// - Place slightly above the floor (~0.1m) to avoid floor collision on spawn
// - Keep clear of obstacles (VR player guardian area is larger than their avatar)
// - Account for VR guardian boundaries — desktop player sizes differ from VR

Required Setup Checklist

□ Exactly one VRCWorld Prefab exists in the scene
□ At least one Transform set in Spawns
□ Respawn Height set to an appropriate value (well below the floor)
□ Reference Camera configured for clipping distances (for VR)
□ Layer/Collision Matrix correctly configured
□ "Setup Layers for VRChat" has been executed

---

Components

MANDATORY READ references/components.md (~800 lines) before configuring any VRC component below. Load in full — dependency requirements and Udon event hooks are distributed throughout. Do NOT Load: references/audio-video.md (unless the task involves audio/video components), references/lighting.md.

VRC_ObjectSync vs UdonSynced

SDK 3.8.0+: Force Kinematic On Remote — Makes Rigidbody kinematic on non-owner clients, preventing unexpected physics behavior.

---

Layers & Collision

VRChat Reserved Layers

Layer Setup Steps

1. VRChat SDK > Show Control Panel
2. Builder tab
3. Click "Setup Layers for VRChat"
4. Collision Matrix is automatically configured

MANDATORY READ references/layers.md when setting up collision or debugging physics. The default Unity collision matrix differs from the VRChat-correct one — always verify. Do NOT Load: references/audio-video.md, references/upload.md.

---

Performance

Target FPS

Critical Limits

Quest/Android Restrictions

Performance Optimization Workflow

MANDATORY READ: Load performance.md before optimizing — measure first, then target the largest bottleneck — and references/lighting.md for Quest optimization. Do NOT Load: references/audio-video.md, references/upload.md.

---

Lighting

Baked Lighting (Required)

✅ Recommended settings:
├── Lightmapper: Progressive GPU
├── Lightmap Resolution: 10-20 texels/unit (PC) / 5-10 (Quest)
├── Light Mode: Baked or Mixed
└── Light Probes: Place along player paths

❌ Avoid:
├── Realtime lights (dynamic shadows)
├── High-resolution lightmaps (memory consumption)
└── Excessive Reflection Probes

MANDATORY READ references/lighting.md when configuring lightmaps or light probe placement. Do NOT Load: references/audio-video.md, references/upload.md, references/layers.md.

---

Audio & Video

VRC_SpatialAudioSource

Plan each world AudioSource with a VRC_SpatialAudioSource: a bare AudioSource triggers a VRChat SDK Build Panel warning. Add the companion deliberately, avoid Auto Fix as a blind default, and do not overwrite existing VRC_SpatialAudioSource values or tuned AudioSource curves unless requested.

When preserving an existing AudioSource, keep volume, spatialBlend, rolloffMode, maxDistance, and custom curves; use Gain 0 dB; enable Use AudioSource Volume Curve for tuned 3D rolloff; match Far to the existing maxDistance or intended audible range; and keep Near at 0m unless an existing minDistance/Near value was intentionally authored.

Video Player Selection

MANDATORY READ references/audio-video.md for VRC_SpatialAudioSource or video player configuration. Optional: references/components.md when wiring audio/video components. Do NOT Load: references/lighting.md, references/performance.md.

---

World Upload

Upload Steps

1. Check Validation
   └── VRChat SDK > Build Panel > Validations

2. Build & Test (local testing)
   └── "Build & Test New Build"
   └── Supports multi-client testing

3. Upload
   └── "Build and Upload"
   └── Set Content Warnings
   └── Set Capacity

4. Publish settings
   └── Configure public/private on the VRChat website

Pre-Upload Checklist

□ VRC_SceneDescriptor × 1
□ Spawns configured
□ Respawn Height appropriate
□ Layer/Collision Matrix verified
□ Light baking complete
□ Mirror default OFF
□ 45+ FPS in VR
□ No Validation errors
□ Content Warnings set
□ Capacity set

MANDATORY READ references/upload.md before running Build & Upload. Verify all pre-upload checklist items first. MANDATORY READ references/build-validation.md when the user asks about SDK Build Panel validation, red/yellow/white warnings, Auto Fix, or a copied validation message. Do NOT Load: references/audio-video.md, references/lighting.md.

---

Troubleshooting

Quick Router

Identify the symptom category and jump to the reference section:

MANDATORY READ references/troubleshooting.md when diagnosing any issue. Do NOT Load for non-troubleshooting tasks.

---

Related Skills

For C# scripting, network sync, and UdonSharp event implementation, use the unity-vrc-udon-sharp skill.

---

Templates (assets/templates/)

Starter templates for common SDK component patterns. Each template compiles without modification; adjust Inspector fields and extend the event stubs for your world.

References