version: "1.0.1" name: unity-vrc-world-sdk-3 description: > VRChat World SDK 3 scene setup and optimization guide. Use this skill when configuring VRChat world scenes, placing SDK components, setting up layers, optimizing performance, or uploading worlds. Covers VRC_SceneDescriptor, spawn points, VRC_Pickup, VRC_Station, VRC_Mirror, VRC_ObjectSync, VRC_CameraDolly, layer/collision matrix, baked lighting, Quest/Android limits, Dynamics for Worlds, and upload workflow. SDK 3.7.1 - 3.10.4 coverage. Triggers on: VRChat world, VRC SDK, scene setup, VRC_SceneDescriptor, spawn point, VRC_Pickup, VRC_Station, VRC_ObjectSync, layer setup, PhysBones, Contacts, Box Contacts, Global Avatar PhysBone Colliders, VRCPhysBoneCollider, VRCTween, optimization, Quest support, light baking, upload, FPS improvement. Related: Use unity-vrc-udon-sharp for UdonSharp C# coding. license: MIT metadata: author: niaka3dayo version: "2.5.0" tags: vrchat, world-sdk, scene-setup, optimization, components, upload

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

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. 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