unity-vrc-world-sdk-3
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseVRChat World SDK 3 Guide
VRChat World SDK 3 指南
Table of Contents
目录
| Section | Content | Reference |
|---|---|---|
| Scene Setup | VRC_SceneDescriptor, Spawn | This file |
| Components | Pickup, Station, Mirror | |
| Layers & Collision | Layers, Collision Matrix | |
| Performance | Optimization guide | |
| Lighting | Lighting settings | |
| Audio & Video | Audio, Video players | |
| World Upload | Upload workflow | |
| Troubleshooting | Problem solving | |
| Cheatsheet | Quick reference | |
| 章节 | 内容 | 参考文档 |
|---|---|---|
| 场景设置 | VRC_SceneDescriptor、出生点 | 本文档 |
| 组件 | Pickup、Station、Mirror | |
| 图层与碰撞 | 图层、碰撞矩阵 | |
| 性能优化 | 性能优化指南 | |
| 光照设置 | 光照配置 | |
| 音频与视频 | 音频、视频播放器 | |
| 世界上传 | 上传工作流 | |
| 故障排除 | 问题解决方法 | |
| 速查表 | 快速参考 | |
SDK Versions
SDK版本
Supported versions: SDK 3.7.1 - 3.10.2 (as of March 2026)
| SDK | New Features | Status |
|---|---|---|
| 3.7.1 | StringBuilder, Regex, System.Random | ✅ |
| 3.7.4 | Persistence API (PlayerData/PlayerObject) | ✅ |
| 3.7.6 | Multi-platform Build & Publish (simultaneous PC + Android builds) | ✅ |
| 3.8.0 | PhysBone dependency sorting, Force Kinematic On Remote, Drone API | ✅ |
| 3.8.1 | [NetworkCallable] events with parameters, | ✅ |
| 3.9.0 | Camera Dolly API, Auto Hold simplification, VRCCameraSettings | ✅ |
| 3.10.0 | Dynamics for Worlds (PhysBones, Contacts, VRC Constraints) | ✅ |
| 3.10.1 | Bug fixes and stability improvements | ✅ |
| 3.10.2 | EventTiming 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.1 | StringBuilder、Regex、System.Random | ✅ 支持 |
| 3.7.4 | 持久化API(PlayerData/PlayerObject) | ✅ 支持 |
| 3.7.6 | 多平台构建与发布(同时构建PC和Android版本) | ✅ 支持 |
| 3.8.0 | PhysBone依赖排序、远程端强制运动学、无人机API | ✅ 支持 |
| 3.8.1 | 带参数的[NetworkCallable]事件、 | ✅ 支持 |
| 3.9.0 | Camera Dolly API、Auto Hold简化、VRCCameraSettings | ✅ 支持 |
| 3.10.0 | 世界动力学系统(PhysBones、Contacts、VRC约束) | ✅ 支持 |
| 3.10.1 | 错误修复与稳定性提升 | ✅ 支持 |
| 3.10.2 | EventTiming扩展、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
所有属性
| Property | Type | Description | Default |
|---|---|---|---|
| Spawns | Transform[] | Array of spawn points | Descriptor position |
| Spawn Order | enum | Sequential/Random/Demo | Sequential |
| Respawn Height | float | Respawn height (Y axis) | -100 |
| Object Behaviour At Respawn | enum | Respawn/Destroy | Respawn |
| Reference Camera | Camera | Player camera settings reference | None |
| Forbid User Portals | bool | Disable user portals | false |
| Voice Falloff Range | float | Voice attenuation range | - |
| Interact Passthrough | LayerMask | Interact passthrough layers | Nothing |
| Maximum Capacity | int | Max player count (hard limit) | - |
| Recommended Capacity | int | Recommended 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 Cameracsharp
// 使用说明:
// 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 boundariescsharp
// 配置步骤:
// 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
组件
| Component | Required Elements | Purpose | SDK |
|---|---|---|---|
| VRC_SceneDescriptor | - | World settings (required) | - |
| VRC_Pickup | Collider + Rigidbody | Grabbable objects | - |
| VRC_Station | Collider | Sittable locations | - |
| VRC_ObjectSync | Rigidbody | Auto-sync Transform/physics | - |
| VRC_MirrorReflection | - | Mirror (⚠️ high cost) | - |
| VRC_PortalMarker | - | Portal to other worlds | - |
| VRC_SpatialAudioSource | AudioSource | 3D audio | - |
| VRC_UIShape | Canvas (World Space) | Unity UI interaction | - |
| VRC_AvatarPedestal | - | Avatar display/switch | - |
| VRC_CameraDolly | - | Camera dolly | 3.9+ |
| 组件名称 | 必填元素 | 用途 | SDK版本要求 |
|---|---|---|---|
| VRC_SceneDescriptor | - | 世界设置(必填) | - |
| VRC_Pickup | Collider + Rigidbody | 可抓取对象 | - |
| VRC_Station | Collider | 可坐立位置 | - |
| VRC_ObjectSync | Rigidbody | 自动同步Transform/物理状态 | - |
| VRC_MirrorReflection | - | 镜子(⚠️性能开销高) | - |
| VRC_PortalMarker | - | 通往其他世界的传送门 | - |
| VRC_SpatialAudioSource | AudioSource | 3D音频 | - |
| VRC_UIShape | Canvas(世界空间) | Unity UI交互 | - |
| VRC_AvatarPedestal | - | 化身展示/切换台 | - |
| VRC_CameraDolly | - | 相机轨道系统 | 3.9+ |
VRC_ObjectSync vs UdonSynced
VRC_ObjectSync 与 UdonSynced 对比
| Scenario | VRC_ObjectSync | UdonSynced variables |
|---|---|---|
| Throwable objects / physics | ✅ Recommended | ❌ |
| State only / complex logic | ❌ | ✅ Recommended |
SDK 3.8.0+:— Makes Rigidbody kinematic on non-owner clients, preventing unexpected physics behavior.Force Kinematic On Remote
→ For detailed properties, Udon events, and code examples, see
references/components.md| 场景 | VRC_ObjectSync | UdonSynced变量 |
|---|---|---|
| 可投掷对象/物理交互 | ✅ 推荐使用 | ❌ 不推荐 |
| 仅状态同步/复杂逻辑 | ❌ 不推荐 | ✅ 推荐使用 |
SDK 3.8.0+新增:— 在非所有者客户端将Rigidbody设置为运动学,避免意外的物理行为。Force Kinematic On Remote
→ 如需详细属性、Udon事件和代码示例,请查看
references/components.mdLayers & Collision
图层与碰撞
VRChat Reserved Layers
VRChat预留图层
| Layer # | Name | Purpose |
|---|---|---|
| 0 | Default | General objects |
| 9 | Player | Remote players |
| 10 | PlayerLocal | Local player |
| 11 | Environment | Environment (walls, floors) |
| 13 | Pickup | Grabbable objects |
| 14 | PickupNoEnvironment | Pickups that don't collide with environment |
| 17 | Walkthrough | Walk-through objects |
| 18 | MirrorReflection | Mirror reflection only |
| 22-31 | User Layers | Available for custom use |
| 图层编号 | 名称 | 用途 |
|---|---|---|
| 0 | Default(默认) | 通用对象 |
| 9 | Player(玩家) | 远程玩家对象 |
| 10 | PlayerLocal(本地玩家) | 本地玩家对象 |
| 11 | Environment(环境) | 环境对象(墙壁、地板) |
| 13 | Pickup(可抓取) | 可抓取对象 |
| 14 | PickupNoEnvironment | 不与环境碰撞的可抓取对象 |
| 17 | Walkthrough(可穿过) | 可穿过的对象 |
| 18 | MirrorReflection(镜子反射) | 仅用于镜子反射的对象 |
| 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.md1. 打开VRChat SDK > Show Control Panel(显示控制面板)
2. 切换到Builder(构建器)标签页
3. 点击"Setup Layers for VRChat"
4. 碰撞矩阵将自动配置完成→ 详细说明请查看
references/layers.mdPerformance
性能优化
Target FPS
目标帧率
| Platform | FPS Target | Measurement Point |
|---|---|---|
| PC VR | 45+ FPS | Spawn point, 1 player |
| PC Desktop | 60+ FPS | Spawn point, 1 player |
| Quest | 72 FPS | Spawn point, 1 player |
| 平台 | 目标帧率 | 测量点 |
|---|---|---|
| PC VR | 45+ FPS | 出生点,单玩家场景 |
| PC 桌面端 | 60+ FPS | 出生点,单玩家场景 |
| Quest | 72 FPS | 出生点,单玩家场景 |
Critical Limits
关键限制
| Item | Recommended | Reason |
|---|---|---|
| Mirrors | 1, default OFF | Renders the entire scene 2x |
| Video players | Max 2 | Decoding overhead |
| Realtime lights | 0-1 | Dynamic shadows are expensive |
| Lightmaps | Required | Performance foundation |
| 项目 | 推荐值 | 原因 |
|---|---|---|
| 镜子 | 最多1个,默认关闭 | 会将整个场景渲染2次 |
| 视频播放器 | 最多2个 | 解码开销大 |
| 实时灯光 | 0-1个 | 动态阴影性能开销极高 |
| 光照贴图 | 必须使用 | 性能优化的基础 |
Quest/Android Restrictions
Quest/Android限制
| Component | PC | Quest |
|---|---|---|
| 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.mdLighting
光照设置
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.mdAudio & Video
音频与视频
VRC_SpatialAudioSource
VRC_SpatialAudioSource
| Property | Description | Default |
|---|---|---|
| Gain | Volume (dB) | 0 (World: +10) |
| Near | Attenuation start | 0m |
| Far | Attenuation end | 40m |
| Volumetric Radius | Source spread | 0m |
| Enable Spatialization | 3D positioning | true |
| 属性名称 | 描述 | 默认值 |
|---|---|---|
| Gain(增益) | 音量(分贝) | 0(世界场景: +10) |
| Near(近距) | 衰减开始距离 | 0m |
| Far(远距) | 衰减结束距离 | 40m |
| Volumetric Radius(体积半径) | 音频源的扩散范围 | 0m |
| Enable Spatialization(启用空间化) | 3D定位开关 | true |
Video Player Selection
视频播放器选择
| Feature | AVPro | Unity Video |
|---|---|---|
| Live streaming | ✅ | ❌ |
| Editor preview | ❌ | ✅ |
| YouTube/Twitch | ✅ | ❌ |
| Quest support | ✅ | ✅ |
→ For details, see
references/audio-video.md| 功能特性 | AVPro | Unity Video |
|---|---|---|
| 直播流支持 | ✅ 支持 | ❌ 不支持 |
| 编辑器预览 | ❌ 不支持 | ✅ 支持 |
| YouTube/Twitch支持 | ✅ 支持 | ❌ 不支持 |
| Quest支持 | ✅ 支持 | ✅ 支持 |
→ 详细说明请查看
references/audio-video.mdWorld 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 website1. 验证检查
└── 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.mdTroubleshooting
故障排除
Common Issues
常见问题
| Issue | Cause | Solution |
|---|---|---|
| Player walks through walls | Wrong layer | Set to Environment |
| Can't grab Pickup | Missing Collider/Rigidbody | Add both |
| Pickup doesn't sync | Missing ObjectSync | Add VRC_ObjectSync |
| Can't sit in Station | Missing Collider | Add Collider |
| Mirror doesn't reflect | Layer settings | Check MirrorReflection |
| Build error | Validation failure | Check SDK Panel |
→ For details, see
references/troubleshooting.md| 问题描述 | 原因 | 解决方法 |
|---|---|---|
| 玩家可以穿过墙壁 | 图层设置错误 | 设置为Environment图层 |
| 无法抓取Pickup对象 | 缺少Collider/Rigidbody组件 | 添加这两个组件 |
| Pickup对象不同步 | 缺少ObjectSync组件 | 添加VRC_ObjectSync组件 |
| 无法坐在Station上 | 缺少Collider组件 | 添加Collider组件 |
| 镜子不显示反射 | 图层设置问题 | 检查MirrorReflection图层 |
| 构建错误 | 验证未通过 | 检查SDK面板的提示信息 |
→ 详细说明请查看
references/troubleshooting.mdRelated Skills
相关技能
| Task | Skill to Use |
|---|---|
| C# code creation | |
| Network sync (Udon) | |
| Event implementation | |
| Scene setup | This skill |
| Component placement | This skill |
| Performance optimization | This skill |
| 任务 | 推荐使用的技能 |
|---|---|
| C#代码编写 | |
| 网络同步(Udon) | |
| 事件实现 | |
| 场景设置 | 本技能 |
| 组件放置 | 本技能 |
| 性能优化 | 本技能 |
Web Search
网页搜索
Official Documentation (WebSearch)
官方文档搜索(WebSearch)
undefinedundefinedSearch official documentation
搜索官方文档
WebSearch: "component or feature to look up site:creators.vrchat.com"
undefinedWebSearch: "要查询的组件或功能 site:creators.vrchat.com"
undefinedIssue Investigation (WebSearch)
问题排查搜索(WebSearch)
undefinedundefinedStep 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"
undefinedWebSearch:
query: "问题描述 site:github.com/vrchat-community"
undefinedOfficial Resources
官方资源
| Resource | URL |
|---|---|
| VRChat Creators | https://creators.vrchat.com/worlds/ |
| VRChat Forums | https://ask.vrchat.com/ |
| VRChat Canny | https://feedback.vrchat.com/ |
| SDK Release Notes | https://creators.vrchat.com/releases/ |
| 资源名称 | URL |
|---|---|
| VRChat创作者平台 | https://creators.vrchat.com/worlds/ |
| VRChat论坛 | https://ask.vrchat.com/ |
| VRChat反馈平台 | https://feedback.vrchat.com/ |
| SDK发布说明 | https://creators.vrchat.com/releases/ |
References
参考文档
| File | Content | Approx. Lines |
|---|---|---|
| All component details | 800+ |
| Layers & collision | 400+ |
| Performance optimization | 500+ |
| Lighting settings | 400+ |
| Audio & video | 400+ |
| Upload procedure | 300+ |
| Troubleshooting guide | 500+ |
| Quick reference | 200+ |
| 文件名称 | 内容 | 大致行数 |
|---|---|---|
| 所有组件详细说明 | 800+ |
| 图层与碰撞详细说明 | 400+ |
| 性能优化详细指南 | 500+ |
| 光照设置详细说明 | 400+ |
| 音频与视频详细说明 | 400+ |
| 上传流程详细说明 | 300+ |
| 故障排除详细指南 | 500+ |
| 快速参考手册 | 200+ |