unity-vrc-world-sdk-3

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

VRChat World SDK 3 Guide

VRChat World SDK 3 指南

Table of Contents

目录

SectionContentReference
Scene SetupVRC_SceneDescriptor, SpawnThis file
ComponentsPickup, Station, Mirror
references/components.md
Layers & CollisionLayers, Collision Matrix
references/layers.md
PerformanceOptimization guide
references/performance.md
LightingLighting settings
references/lighting.md
Audio & VideoAudio, Video players
references/audio-video.md
World UploadUpload workflow
references/upload.md
TroubleshootingProblem solving
references/troubleshooting.md
CheatsheetQuick reference
CHEATSHEET.md

章节内容参考文档
场景设置VRC_SceneDescriptor、出生点本文档
组件Pickup、Station、Mirror
references/components.md
图层与碰撞图层、碰撞矩阵
references/layers.md
性能优化性能优化指南
references/performance.md
光照设置光照配置
references/lighting.md
音频与视频音频、视频播放器
references/audio-video.md
世界上传上传工作流
references/upload.md
故障排除问题解决方法
references/troubleshooting.md
速查表快速参考
CHEATSHEET.md

SDK Versions

SDK版本

Supported versions: SDK 3.7.1 - 3.10.2 (as of March 2026)
SDKNew FeaturesStatus
3.7.1StringBuilder, Regex, System.Random
3.7.4Persistence API (PlayerData/PlayerObject)
3.7.6Multi-platform Build & Publish (simultaneous PC + Android builds)
3.8.0PhysBone dependency sorting, Force Kinematic On Remote, Drone API
3.8.1[NetworkCallable] events with parameters,
Others
/
Self
targets
3.9.0Camera Dolly API, Auto Hold simplification, VRCCameraSettings
3.10.0Dynamics for Worlds (PhysBones, Contacts, VRC Constraints)
3.10.1Bug fixes and stability improvements
3.10.2EventTiming extensions, PhysBones fixes, shader time globals✅ Latest stable
Important: SDK versions below 3.9.0 are deprecated as of December 2, 2025. New world uploads are no longer possible with these versions.

支持版本: SDK 3.7.1 - 3.10.2(截至2026年3月)
SDK版本新功能状态
3.7.1StringBuilder、Regex、System.Random✅ 支持
3.7.4持久化API(PlayerData/PlayerObject)✅ 支持
3.7.6多平台构建与发布(同时构建PC和Android版本)✅ 支持
3.8.0PhysBone依赖排序、远程端强制运动学、无人机API✅ 支持
3.8.1带参数的[NetworkCallable]事件
Others
/
Self
目标选项
✅ 支持
3.9.0Camera Dolly API、Auto Hold简化、VRCCameraSettings✅ 支持
3.10.0世界动力学系统(PhysBones、Contacts、VRC约束)✅ 支持
3.10.1错误修复与稳定性提升✅ 支持
3.10.2EventTiming扩展、PhysBones修复、着色器时间全局变量✅ 最新稳定版
重要提示: 截至2025年12月2日,低于3.9.0的SDK版本已被弃用。使用这些版本无法上传新的世界。

Scene Setup

场景设置

VRC_SceneDescriptor (Required)

VRC_SceneDescriptor(必填)

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)
每个VRChat世界中必须且只能存在一个该组件。
[VRCWorld 预制体]
├── VRC_SceneDescriptor(必填)
├── VRC_PipelineManager(自动添加)
├── VRCWorldSettings(可选 - 移动速度设置)
└── AvatarScalingSettings(可选 - 化身缩放限制)

All Properties

所有属性

PropertyTypeDescriptionDefault
SpawnsTransform[]Array of spawn pointsDescriptor position
Spawn OrderenumSequential/Random/DemoSequential
Respawn HeightfloatRespawn height (Y axis)-100
Object Behaviour At RespawnenumRespawn/DestroyRespawn
Reference CameraCameraPlayer camera settings referenceNone
Forbid User PortalsboolDisable user portalsfalse
Voice Falloff RangefloatVoice attenuation range-
Interact PassthroughLayerMaskInteract passthrough layersNothing
Maximum CapacityintMax player count (hard limit)-
Recommended CapacityintRecommended player count (UI)-
属性名称类型描述默认值
Spawns(出生点)Transform[]出生点数组Descriptor对象位置
Spawn Order(出生顺序)枚举类型顺序/随机/演示模式顺序模式
Respawn Height(重生高度)float重生高度(Y轴)-100
Object Behaviour At Respawn(重生时对象行为)枚举类型重生/销毁重生
Reference Camera(参考相机)Camera玩家相机设置参考
Forbid User Portals(禁止用户传送门)bool禁用用户创建的传送门false
Voice Falloff Range(语音衰减范围)float语音衰减的有效范围-
Interact Passthrough(交互穿透层)LayerMask可交互穿透的图层
Maximum Capacity(最大容量)int最大玩家数量(硬限制)-
Recommended Capacity(推荐容量)int推荐玩家数量(UI显示)-

Spawn Order Behavior

出生顺序行为

Sequential: 0 → 1 → 2 → 0 → 1 → 2... (in order)
Random:     Random selection
Demo:       All players spawn at Spawns[0]
Sequential(顺序): 0 → 1 → 2 → 0 → 1 → 2...(按数组顺序循环)
Random(随机):     随机选择出生点
Demo(演示):       所有玩家都在Spawns[0]出生

Reference Camera Usage

参考相机使用方法

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

// Setup steps:
// 1. Create a Camera (name: "ReferenceCamera")
// 2. Adjust Camera component settings
// 3. Disable the Camera (uncheck the component)
// 4. Assign it to VRC_SceneDescriptor's Reference Camera
csharp
// 使用说明:
// 1. 调整近裁剪面/远裁剪面(VR推荐值: 0.01 ~ 1000)
// 2. 应用后期处理效果
// 3. 设置背景颜色

// 配置步骤:
// 1. 创建一个Camera对象(命名: "ReferenceCamera")
// 2. 调整Camera组件的设置
// 3. 禁用该Camera(取消勾选组件)
// 4. 将其分配给VRC_SceneDescriptor的Reference Camera属性

Spawn Points Setup

出生点设置

csharp
// Setup steps:
// 1. Create an empty GameObject
// 2. Set position and rotation (players face the Z+ direction)
// 3. Add to the VRC_SceneDescriptor Spawns array

// Recommendations:
// - At least 2-3 spawn points (for simultaneous joins)
// - Slightly above the floor (~0.1m)
// - Clear of obstacles
// - Account for VR player guardian boundaries
csharp
// 配置步骤:
// 1. 创建一个空的GameObject
// 2. 设置位置和旋转(玩家将面向Z+方向)
// 3. 添加到VRC_SceneDescriptor的Spawns数组中

// 推荐建议:
// - 至少设置2-3个出生点(应对同时加入的玩家)
// - 位置略高于地面(约0.1米)
// - 远离障碍物
// - 考虑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

□ 场景中存在且仅存在一个VRCWorld预制体
□ Spawns数组中至少设置了一个Transform
□ 重生高度设置为合适的值(远低于地面)
□ 参考相机已配置裁剪距离(针对VR)
□ 图层/碰撞矩阵配置正确
□ 已执行"Setup Layers for VRChat"操作

Components

组件

ComponentRequired ElementsPurposeSDK
VRC_SceneDescriptor-World settings (required)-
VRC_PickupCollider + RigidbodyGrabbable objects-
VRC_StationColliderSittable locations-
VRC_ObjectSyncRigidbodyAuto-sync Transform/physics-
VRC_MirrorReflection-Mirror (⚠️ high cost)-
VRC_PortalMarker-Portal to other worlds-
VRC_SpatialAudioSourceAudioSource3D audio-
VRC_UIShapeCanvas (World Space)Unity UI interaction-
VRC_AvatarPedestal-Avatar display/switch-
VRC_CameraDolly-Camera dolly3.9+
组件名称必填元素用途SDK版本要求
VRC_SceneDescriptor-世界设置(必填)-
VRC_PickupCollider + Rigidbody可抓取对象-
VRC_StationCollider可坐立位置-
VRC_ObjectSyncRigidbody自动同步Transform/物理状态-
VRC_MirrorReflection-镜子(⚠️性能开销高)-
VRC_PortalMarker-通往其他世界的传送门-
VRC_SpatialAudioSourceAudioSource3D音频-
VRC_UIShapeCanvas(世界空间)Unity UI交互-
VRC_AvatarPedestal-化身展示/切换台-
VRC_CameraDolly-相机轨道系统3.9+

VRC_ObjectSync vs UdonSynced

VRC_ObjectSync 与 UdonSynced 对比

ScenarioVRC_ObjectSyncUdonSynced variables
Throwable objects / physics✅ Recommended
State only / complex logic✅ Recommended
SDK 3.8.0+:
Force Kinematic On Remote
— Makes Rigidbody kinematic on non-owner clients, preventing unexpected physics behavior.
→ For detailed properties, Udon events, and code examples, see
references/components.md

场景VRC_ObjectSyncUdonSynced变量
可投掷对象/物理交互✅ 推荐使用❌ 不推荐
仅状态同步/复杂逻辑❌ 不推荐✅ 推荐使用
SDK 3.8.0+新增:
Force Kinematic On Remote
— 在非所有者客户端将Rigidbody设置为运动学,避免意外的物理行为。
→ 如需详细属性、Udon事件和代码示例,请查看
references/components.md

Layers & Collision

图层与碰撞

VRChat Reserved Layers

VRChat预留图层

Layer #NamePurpose
0DefaultGeneral objects
9PlayerRemote players
10PlayerLocalLocal player
11EnvironmentEnvironment (walls, floors)
13PickupGrabbable objects
14PickupNoEnvironmentPickups that don't collide with environment
17WalkthroughWalk-through objects
18MirrorReflectionMirror reflection only
22-31User LayersAvailable for custom use
图层编号名称用途
0Default(默认)通用对象
9Player(玩家)远程玩家对象
10PlayerLocal(本地玩家)本地玩家对象
11Environment(环境)环境对象(墙壁、地板)
13Pickup(可抓取)可抓取对象
14PickupNoEnvironment不与环境碰撞的可抓取对象
17Walkthrough(可穿过)可穿过的对象
18MirrorReflection(镜子反射)仅用于镜子反射的对象
22-31用户自定义图层可用于自定义用途

Layer Setup Steps

图层配置步骤

1. VRChat SDK > Show Control Panel
2. Builder tab
3. Click "Setup Layers for VRChat"
4. Collision Matrix is automatically configured
→ For details, see
references/layers.md

1. 打开VRChat SDK > Show Control Panel(显示控制面板)
2. 切换到Builder(构建器)标签页
3. 点击"Setup Layers for VRChat"
4. 碰撞矩阵将自动配置完成
→ 详细说明请查看
references/layers.md

Performance

性能优化

Target FPS

目标帧率

PlatformFPS TargetMeasurement Point
PC VR45+ FPSSpawn point, 1 player
PC Desktop60+ FPSSpawn point, 1 player
Quest72 FPSSpawn point, 1 player
平台目标帧率测量点
PC VR45+ FPS出生点,单玩家场景
PC 桌面端60+ FPS出生点,单玩家场景
Quest72 FPS出生点,单玩家场景

Critical Limits

关键限制

ItemRecommendedReason
Mirrors1, default OFFRenders the entire scene 2x
Video playersMax 2Decoding overhead
Realtime lights0-1Dynamic shadows are expensive
LightmapsRequiredPerformance foundation
项目推荐值原因
镜子最多1个,默认关闭会将整个场景渲染2次
视频播放器最多2个解码开销大
实时灯光0-1个动态阴影性能开销极高
光照贴图必须使用性能优化的基础

Quest/Android Restrictions

Quest/Android限制

ComponentPCQuest
Dynamic Bones❌ Disabled
Cloth❌ Disabled
Post-Processing❌ Disabled
Unity Constraints❌ Disabled
Realtime lights⚠️ Avoid
→ For details, see
references/performance.md

组件名称PC端Quest端
Dynamic Bones✅ 支持❌ 已禁用
Cloth(布料)✅ 支持❌ 已禁用
Post-Processing(后期处理)✅ 支持❌ 已禁用
Unity Constraints(Unity约束)✅ 支持❌ 已禁用
实时灯光✅ 支持⚠️ 建议避免使用
→ 详细说明请查看
references/performance.md

Lighting

光照设置

Baked Lighting (Required)

烘焙光照(必须使用)

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

❌ Avoid:
├── Realtime lights (dynamic shadows)
├── High-resolution lightmaps (memory consumption)
└── Excessive Reflection Probes
→ For details, see
references/lighting.md

✅ 推荐设置:
├── 光照烘焙器: Progressive GPU
├── 光照贴图分辨率: 10-20 texels/unit
├── 灯光模式: Baked(烘焙)或Mixed(混合)
└── 光照探针: 放置在玩家移动路径上

❌ 需避免:
├── 实时灯光(动态阴影)
├── 高分辨率光照贴图(内存占用过高)
└── 过多的反射探针
→ 详细说明请查看
references/lighting.md

Audio & Video

音频与视频

VRC_SpatialAudioSource

VRC_SpatialAudioSource

PropertyDescriptionDefault
GainVolume (dB)0 (World: +10)
NearAttenuation start0m
FarAttenuation end40m
Volumetric RadiusSource spread0m
Enable Spatialization3D positioningtrue
属性名称描述默认值
Gain(增益)音量(分贝)0(世界场景: +10)
Near(近距)衰减开始距离0m
Far(远距)衰减结束距离40m
Volumetric Radius(体积半径)音频源的扩散范围0m
Enable Spatialization(启用空间化)3D定位开关true

Video Player Selection

视频播放器选择

FeatureAVProUnity Video
Live streaming
Editor preview
YouTube/Twitch
Quest support
→ For details, see
references/audio-video.md

功能特性AVProUnity Video
直播流支持✅ 支持❌ 不支持
编辑器预览❌ 不支持✅ 支持
YouTube/Twitch支持✅ 支持❌ 不支持
Quest支持✅ 支持✅ 支持
→ 详细说明请查看
references/audio-video.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
1. 验证检查
   └── VRChat SDK > Build Panel > Validations

2. 构建与测试(本地测试)
   └── "Build & Test New Build"
   └── 支持多客户端测试

3. 上传
   └── "Build and Upload"
   └── 设置内容警告
   └── 设置玩家容量

4. 发布设置
   └── 在VRChat网站配置公开/私有状态

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
→ For details, see
references/upload.md

□ 存在且仅存在一个VRC_SceneDescriptor
□ 已配置出生点
□ 重生高度设置合理
□ 图层/碰撞矩阵已验证正确
□ 光照烘焙已完成
□ 镜子默认处于关闭状态
□ VR场景帧率达到45+ FPS
□ 无验证错误
□ 已设置内容警告
□ 已设置玩家容量
→ 详细说明请查看
references/upload.md

Troubleshooting

故障排除

Common Issues

常见问题

IssueCauseSolution
Player walks through wallsWrong layerSet to Environment
Can't grab PickupMissing Collider/RigidbodyAdd both
Pickup doesn't syncMissing ObjectSyncAdd VRC_ObjectSync
Can't sit in StationMissing ColliderAdd Collider
Mirror doesn't reflectLayer settingsCheck MirrorReflection
Build errorValidation failureCheck SDK Panel
→ For details, see
references/troubleshooting.md

问题描述原因解决方法
玩家可以穿过墙壁图层设置错误设置为Environment图层
无法抓取Pickup对象缺少Collider/Rigidbody组件添加这两个组件
Pickup对象不同步缺少ObjectSync组件添加VRC_ObjectSync组件
无法坐在Station上缺少Collider组件添加Collider组件
镜子不显示反射图层设置问题检查MirrorReflection图层
构建错误验证未通过检查SDK面板的提示信息
→ 详细说明请查看
references/troubleshooting.md

Related Skills

相关技能

TaskSkill to Use
C# code creation
unity-vrc-udon-sharp
Network sync (Udon)
unity-vrc-udon-sharp
Event implementation
unity-vrc-udon-sharp
Scene setupThis skill
Component placementThis skill
Performance optimizationThis skill

任务推荐使用的技能
C#代码编写
unity-vrc-udon-sharp
网络同步(Udon)
unity-vrc-udon-sharp
事件实现
unity-vrc-udon-sharp
场景设置本技能
组件放置本技能
性能优化本技能

Web Search

网页搜索

Official Documentation (WebSearch)

官方文档搜索(WebSearch)

undefined
undefined

Search official documentation

搜索官方文档

WebSearch: "component or feature to look up site:creators.vrchat.com"
undefined
WebSearch: "要查询的组件或功能 site:creators.vrchat.com"
undefined

Issue Investigation (WebSearch)

问题排查搜索(WebSearch)

undefined
undefined

Step 1: Forum search

步骤1: 论坛搜索

WebSearch: query: "issue description site:ask.vrchat.com" allowed_domains: ["ask.vrchat.com"]
WebSearch: query: "问题描述 site:ask.vrchat.com" allowed_domains: ["ask.vrchat.com"]

Step 2: Known bug search

步骤2: 已知Bug搜索

WebSearch: query: "issue description site:feedback.vrchat.com" allowed_domains: ["feedback.vrchat.com"]
WebSearch: query: "问题描述 site:feedback.vrchat.com" allowed_domains: ["feedback.vrchat.com"]

Step 3: GitHub Issues

步骤3: GitHub Issues搜索

WebSearch: query: "issue description site:github.com/vrchat-community"
undefined
WebSearch: query: "问题描述 site:github.com/vrchat-community"
undefined

Official Resources

官方资源

References

参考文档

FileContentApprox. Lines
references/components.md
All component details800+
references/layers.md
Layers & collision400+
references/performance.md
Performance optimization500+
references/lighting.md
Lighting settings400+
references/audio-video.md
Audio & video400+
references/upload.md
Upload procedure300+
references/troubleshooting.md
Troubleshooting guide500+
CHEATSHEET.md
Quick reference200+
文件名称内容大致行数
references/components.md
所有组件详细说明800+
references/layers.md
图层与碰撞详细说明400+
references/performance.md
性能优化详细指南500+
references/lighting.md
光照设置详细说明400+
references/audio-video.md
音频与视频详细说明400+
references/upload.md
上传流程详细说明300+
references/troubleshooting.md
故障排除详细指南500+
CHEATSHEET.md
快速参考手册200+