version: "1.0.5" name: unity-vrc-world-sdk-3 description: > VRChat World SDK 3 guide for scene and Inspector setup, component placement, optimization, and upload. Use for VRChat world scene configuration, VRC SDK components, layers, baked lighting, Quest/Android performance, Dynamics for Worlds, Build Panel warning triage, validation, and upload. Covers VRC_SceneDescriptor, VRC_Pickup, VRC_Station, VRC_Mirror, VRC_ObjectSync, VRC_CameraDolly, spawn points, collision matrices, PhysBone and Contact component placement, Box Contacts, Global Avatar PhysBone Colliders, and VRCPhysBoneCollider component setup. SDK 3.7.1-3.10.4. Triggers on: VRChat world scene, VRC SDK, scene setup, component placement, optimization, Quest support, light baking, upload, SDK validation, Build Panel warning, Auto Fix, red warning, yellow warning, or white warning. Do not use for UdonSharp C# or VRCTween calls; use unity-vrc-udon-sharp for runtime scripting. license: MIT metadata: author: niaka3dayo version: "3.0.1" tags: vrchat, world-sdk, scene-setup, optimization, components, upload, sdk-validation, build-panel

VRChat World SDK 3 Guide

Table of Contents

Method Migration

The following public methods were renamed because an unprefixed, parameterless public UdonSharp method remains callable through legacy network dispatch:

Update Inspector event strings, SendCustomEvent* calls, delayed events and nameof(...) expressions, and cross-behaviour calls. Compatibility aliases are not provided because an old unprefixed alias would restore the same legacy network exposure.

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

If the world must run on Android, decide those constraints before tuning the PC build. Test each target separately.

Android headsets have mobile CPU, GPU, memory, and thermal budgets that differ from PC and vary by device:

• GPU: Realtime lights, shadows, overdraw, and complex shaders can dominate frame time
• Memory: Textures and lightmaps share limited system memory with the client
• Thermals: Sustained load can reduce available performance during a session

Measure each target device independently; PC results do not establish Android performance, and a single-client Quest result does not predict a particular PC frame rate. Use the Unity Profiler and the official Android content optimization guide 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: World shaders are unrestricted; prefer mobile-compatible shaders and profile custom ones
  ├── Lighting: Baked by default; retain realtime effects only after target-device profiling
  ├── Geometry: Budget approximately 250,000 triangles for the whole world; reduce further when profiling calls for it
  ├── Materials: Minimize unique materials and draw calls; no fixed world upload limit is documented
  ├── Audio: Mono, compressed, limited concurrent sources
  └── Physics: Simplified colliders, minimal Rigidbodies

SDK Versions

Covered versions: SDK 3.7.1 - 3.10.4 (last verified: 3.10.4)

Use the current supported SDK for publishing and verify version-sensitive APIs against the matching release notes before migrating a project.

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)

Key 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

Performance Criteria

Define the performance target from the supported devices, representative scenes, and expected player count. Record a frame-time or frame-rate target for each build target before profiling. VRChat does not provide one fixed FPS upload threshold for worlds.

Starting Budgets

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 (Default)

✅ Recommended settings:
├── Lightmapper: Progressive GPU
├── Lightmap Resolution: 10-20 texels/unit (PC) / 5-10 (Quest)
├── Light Mode: Baked by default; use Mixed/Realtime only when the effect is necessary and measured
└── 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
□ Project-defined frame-time or frame-rate target met in representative scenes and player counts
□ 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. Repository checks cover static checks; import them into the target SDK project, compile, and run Build & Test before use. Adjust Inspector fields and extend the event stubs for your world.

References