unity-vrc-world-sdk-3

VRChat World SDK 3 指南

目录

章节	内容	参考资料
场景设置	VRC_SceneDescriptor、生成点	本文件
组件	Pickup、Station、Mirror	references/components.md
图层与碰撞	图层、碰撞矩阵	references/layers.md
性能	优化指南	references/performance.md
光照	光照设置	references/lighting.md
音频与视频	音频、视频播放器	references/audio-video.md
构建验证	红色／黄色／白色 SDK 警告	references/build-validation.md
世界上传	上传工作流	references/upload.md
故障排除	问题解决	references/troubleshooting.md
速查表	快速参考	CHEATSHEET.md

---

方法迁移

以下公共方法已重命名，因为未添加前缀且不带参数的公共 UdonSharp 方法仍可通过旧版网络分发调用：

之前	之后
ForceDropPickup	_ForceDropPickup
IsHeld	_IsHeld
IsOccupied	_IsOccupied
StopSound	_StopSound
SlowUpdate	_SlowUpdate

请更新 Inspector 事件字符串、SendCustomEvent* 调用、延迟事件和 nameof(...) 表达式，以及跨行为调用。不提供兼容别名， 因为旧的无前缀别名会重新带来相同的旧版网络暴露风险。

---

常见错误（绝对不要做）

这些错误会导致世界无声无息地失效、性能灾难或与 Quest 不兼容：

#	绝对不要这样做	造成的影响	应改用
1	默认启用镜子（加入世界时处于开启状态）	镜子会增加一次代价高昂的场景渲染；具体影响取决于视野、场景、分辨率和设备	默认关闭镜子；添加由玩家控制的开关，并在每台目标设备上进行性能分析
2	不经性能分析就使用带实时阴影的实时方向光	实时阴影的开销取决于场景几何、视野和目标设备，在 Android 上可能占用大量帧时间	优先使用烘焙光照贴图和光照探针；保留任何实时阴影前，先在目标设备上进行性能分析
3	将重生高度设为等于或高于世界地面	玩家重生 → 坠落 → 再次重生 → 无限循环；玩家无法脱困	将其设为无法到达的深度（例如：地面位于 Y=0 → 将重生高度设为 Y=-100）
4	在新项目中跳过“为 VRChat 设置图层”	图层碰撞矩阵默认设置有误——玩家会穿墙，拾取物会穿透地板	放置任何碰撞体前，运行 VRChat SDK > Builder > “为 VRChat 设置图层”
5	未设置 Android 构建配置就启用后期处理	后期处理在 Android 运行时会被禁用，因此制作的效果不会显示，不必要的资源却仍可能增大构建体积	使用移除了后期处理的独立 Android 构建配置
6	同时放置超过 2 个处于活动状态的视频播放器	每个播放器都会增加显著的解码开销；实际使用中，同时运行 >2 个播放器是导致掉帧和音频问题的常见原因	在场景开始时禁用多余的播放器；仅启用当前正在播放的播放器
7	在 Android 上使用 Cloth，或不经性能分析就添加大量 Unity Constraints	Cloth 在 Android 上已禁用。世界中允许使用 Unity Constraints，但过度使用会显著影响性能	从 Android 构建中移除 Cloth；新项目优先使用 VRC Constraints，并对任何大量使用约束的配置进行性能分析
8	未完成光照贴图烘焙就上传	实时 GI 会产生大量依赖场景的渲染开销，不适合作为未经测量的 Android 备用方案	上传前烘焙光照，然后在目标设备上验证效果
9	将玩家可行走的表面放在 Default 图层（0）上	碰撞矩阵默认设置有误——Avatar 物理碰撞不可靠；玩家可能会穿透几何体	所有可行走的几何体、墙壁和地板均使用 Environment（图层 11）
10	不经性能分析就为大面积区域设置极高的光照贴图分辨率	高分辨率下纹理内存可能大幅增加；这是移动头显发生 OOM 崩溃的常见原因	可将 10-20 texels/unit（PC）/ 5-10（Quest）作为实用的起始指南；分析 VRAM 并进行调整——官方指南建议 Quest“保持较低的光照贴图分辨率”
11	将 VRC_UIShape 添加到屏幕空间或叠加 Canvas	VRC_UIShape 需要使用世界空间 Canvas；其他模式会在 VRChat 中触发 Unity 运行时错误——UI 虽然会显示，但无法交互，世界创建者也看不到错误提示	添加 VRC_UIShape 前，将 Canvas > Render Mode 设为 World Space

参考资料加载指南

仅加载任务所需的内容。

任务	必须阅读	可选	不要加载	加载理由
从头开始设置新场景	components.md、layers.md	upload.md	audio-video.md、troubleshooting.md	碰撞矩阵不易理解；需要提前了解组件依赖项
让物体可抓取（VRC_Pickup）	components.md	layers.md	audio-video.md、lighting.md	Pickup/Rigidbody 的要求未包含在标准 Unity 文档中
为 Worlds 配置 Dynamics（PhysBones、Contacts、Box Contacts、Global Avatar PhysBone Colliders、world VRCPhysBoneCollider 访问）	components.md	layers.md、troubleshooting.md；Udon 代码请使用 unity-vrc-udon-sharp	audio-video.md、lighting.md	Dynamics 组件的可用性和 Udon 访问方式受 SDK 版本影响
设置座位（VRC_Station）	components.md	layers.md	audio-video.md、performance.md	Station 的碰撞体和退出要求是 VRChat 特有的
优化 Quest 的 FPS	performance.md、lighting.md	troubleshooting.md	audio-video.md、upload.md	Quest 的限制与 PC 不同；烘焙要求不易理解
添加音频或视频播放器／语音区域（SetVoiceGain、Steam Audio）	audio-video.md、components.md	troubleshooting.md	lighting.md、performance.md	选择 AVPro 还是 Unity Video 是 VRChat 特有的问题
配置 WorldQualitySettings、实时探针或 Shadowmask Mode	components.md	lighting.md；Udon API：unity-vrc-udon-sharp	audio-video.md、layers.md	现有的启动设置器和覆盖标志可能会覆盖已设定的画质选项
烘焙灯光／设置光照贴图	lighting.md、performance.md	—	audio-video.md、layers.md	光照贴图分辨率和探针位置会影响 Quest 的 VRAM
SDK Build Panel 验证提醒、红色／黄色／白色警告或 Auto Fix 相关问题	build-validation.md	upload.md、troubleshooting.md	audio-video.md、lighting.md	提醒级别、构建影响和 Auto Fix 的副作用必须以 SDK 支持的目录为准
上传并发布 World	upload.md	build-validation.md、troubleshooting.md	audio-video.md、lighting.md	上传步骤和验证顺序容易出错，很容易遗漏
排查碰撞或图层问题	layers.md、troubleshooting.md	components.md	audio-video.md、lighting.md	VRChat 的碰撞矩阵与 Unity 默认设置不同
设置和配置镜像	components.md	performance.md	audio-video.md、upload.md	镜像图层遮罩要求是 VRChat 特有的

创建新 World 前——设计决策

这些决策会影响后续的每项选择。请先做出决策，再放置任何组件。

决策	选项	影响
是否必须支持 Quest？	是／否	是 → 从第 0 天起就采用 Quest First 理念，而不是事后改造
预计玩家人数？	1–8／9–40／40+	影响出生点数量、镜像策略和视频播放器上限
主要交互方式？	抓取（Pickup）／坐下（Station）／观看（Video）／探索	决定哪些 SDK 组件是必需的
灯光方案？	烘焙／混合／实时	Android 上优先使用烘焙灯光；保留实时灯光或阴影前，先在每个目标设备上进行性能分析
是否有联网对象？	无／物理（Pickup+ObjectSync）／状态（UdonSynced）	决定开始编写 Udon 脚本前所需的同步架构

---

设计理念：Quest 优先

如果世界必须在 Android 上运行，就要在调整 PC 版本之前确定这些限制。分别测试每个目标平台。

Android 头显的移动 CPU、GPU、内存和散热预算与 PC 不同，并且会因设备而异：

• GPU：实时光照、阴影、过度绘制和复杂着色器可能占用大量帧时间
• 内存：纹理和光照贴图需要与客户端共享有限的系统内存
• 散热：持续负载可能会降低会话期间可用的性能

分别测量每台目标设备；PC 测试结果无法证明 Android 的性能，单台 Quest 客户端的测试结果也无法预测特定 PC 的帧率。发布前，请使用 Unity Profiler 和官方 Android 内容优化指南。

绝不要只为 PC 优化，再“稍后添加 Quest 支持”——届时，光照、材质和网格密度都已锁定为 PC 画质，而 Quest 移植则需要重做一切。

Quest 优先级联效应——如果必须支持 Quest，那么所有后续决策都必须遵循相应限制：

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 版本

当前支持版本／最后验证版本：SDK 3.10.5

从 v4.0.0 起，策略为仅支持最新稳定版 SDK；只有在本仓库验证新的稳定版本后，才会切换支持版本。新发布的稳定版本不会自动获得支持。目前最后验证的目标版本：3.10.5。

下表保留了功能引入历史，供迁移参考。SDK 3.7.1-3.10.4 条目仅供历史参考；它们不是此 Skill 的当前支持版本或验证目标。这是此 Skill 的支持范围，并不代表 VRChat 自身的 SDK 策略。除非参考资料明确标注为历史迁移案例，否则主要生成示例均以 SDK 3.10.5 为目标版本。

SDK	新功能	状态
3.7.1	StringBuilder、Regex、System.Random	历史版本
3.7.4	持久化 API (PlayerData/PlayerObject)	历史版本
3.7.6	多平台构建与发布（同时构建 PC + Android 版本）	历史版本
3.8.0	PhysBone 依赖排序、强制远程对象设为 Kinematic、Drone API	历史版本
3.8.1	带参数的 [NetworkCallable] 事件、Others/Self 目标、VRCCameraSettings	历史版本
3.9.0	Camera Dolly API、Auto Hold 简化、VRCCameraSettings 新增功能（CullingMask、GetCurrentCamera）	历史版本
3.10.0	世界动态系统（PhysBones、Contacts、VRC Constraints）	历史版本
3.10.1	错误修复和稳定性改进	历史版本
3.10.2	EventTiming 扩展、PhysBones 修复、着色器时间全局变量	历史版本
3.10.3	VRCPlayerApi.isVRCPlus、VRCRaycast（头像）、Mirror 渲染顺序修复	历史版本
3.10.4	VRCTween、盒形 Contacts、全局 Avatar PhysBone Colliders、世界 VRCPhysBoneCollider Udon 访问权限、Data Container 容量 API	历史版本
3.10.5	WorldQualitySettings、Pickup Outline Renderers、Pipeline Manager 验证；可写入的 VRCQualitySettings 和 Assembly Version Defines → UdonSharp Skill	当前支持／最后验证版本

发布时请使用 SDK 3.10.5；迁移项目之前，请根据对应版本的发行说明验证与版本相关的 API。

---

场景设置

VRC_SceneDescriptor（必需）

每个 VRChat 世界中必须且只能有一个。

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

关键属性

属性	类型	描述	默认值
Spawns	Transform[]	生成点数组	描述符位置
Spawn Order	enum	First/Sequential/Random/Demo（First：始终使用第一个生成点；Demo：生成点位于房间规模的中心）	Sequential
Spawn Orientation	enum	Default/Align Player With Spawn Point/Align Room With Spawn Point	Default
Respawn Height	float	重生高度（Y 轴）	-100
Object Behaviour At Respawn	enum	重生/销毁	Respawn
Reference Camera	Camera	玩家摄像机设置参考	None
Forbid User Portals	bool	禁用用户传送门	false
Voice Falloff Range	float	语音衰减范围	-
Interact Passthrough	LayerMask	交互直通层	Nothing
Maximum Capacity	int	最大玩家数量（硬性限制）	-
Recommended Capacity	int	推荐玩家数量（UI）	-

参考摄像机用法

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

必需设置检查清单

□ 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

---

组件

务必阅读 references/components.md（约 800 行），然后再配置以下任何 VRC 组件。请完整加载 — 依赖项要求和 Udon 事件钩子分散在全文各处。 不要加载：references/audio-video.md（除非任务涉及音频/视频组件）、references/lighting.md。

组件	必需元素	用途	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 (World Space)	Unity UI 交互	-
VRC_AvatarPedestal	-	Avatar 显示/切换	-
VRC_CameraDolly	-	摄像机轨道	3.9+
VRCCameraSettings	None (static API)	从 Udon 读取摄像机信息	3.8.1+

VRC_ObjectSync 与 UdonSynced 对比

场景	VRC_ObjectSync	UdonSynced 变量
可投掷物体/物理效果	✅ 推荐	❌
仅状态/复杂逻辑	❌	✅ 推荐

SDK 3.8.0+：Force Kinematic On Remote — 使非所有者客户端上的 Rigidbody 设为运动学状态，防止出现意外的物理行为。

---

层与碰撞

VRChat 保留层

Layer #	Name	Purpose
0	Default	通用对象
9	Player	远程玩家
10	PlayerLocal	本地玩家
11	Environment	环境（墙壁、地板）
13	Pickup	可抓取对象
14	PickupNoEnvironment	不与环境碰撞的可拾取对象
17	Walkthrough	可穿过的对象
18	MirrorReflection	仅用于镜面反射
22-31	User Layers	可供自定义使用

层设置步骤

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

必须阅读 references/layers.md，以设置碰撞或调试物理效果。Unity 默认的碰撞矩阵与 VRChat 正确的配置不同，因此务必进行核实。 不要加载：references/audio-video.md、references/upload.md。

---

性能

性能标准

根据支持的设备、代表性场景和预期玩家数量，设定性能目标。在分析性能前，为每个构建目标记录帧时间或帧率目标。VRChat 没有为世界上传设定统一的 FPS 门槛。

初始预算

项目	建议	原因
镜子	1 个，默认关闭	以 2 倍渲染整个场景
视频播放器	建议 1-2 个	解码开销；没有文档说明的硬性上限
实时光照	默认烘焙	只有在目标设备上分析性能后，才保留实时灯光或阴影
光照贴图	烘焙并验证	Android 的主要光照路径

Quest/Android 限制

组件	PC	Quest
Dynamic Bones	✅	❌ 已禁用
Cloth	✅	❌ 已禁用
Post-Processing	✅	❌ 已禁用
Unity Constraints	✅	✅ 可在世界中使用；需分析性能开销
实时灯光	✅	⚠️ 开销较大；仅在有设备测试依据时保留

性能优化工作流

瓶颈类型	主要指标	参考
CPU 瓶颈	脚本耗时高、物理开销大	performance.md §优化工作流
GPU 瓶颈	绘制调用、过度绘制、着色器复杂度	performance.md §优化工作流
内存	VRAM 使用量、纹理大小、网格数量	performance.md §优化工作流

必须阅读：performance.md，在优化前先进行测量，然后针对最大的瓶颈进行优化；Quest 优化还需阅读 references/lighting.md。 不要加载：references/audio-video.md、references/upload.md。

---

光照

烘焙光照（默认）

✅ 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

必须阅读 references/lighting.md，以配置光照贴图或设置光照探针位置。 不要加载：references/audio-video.md、references/upload.md、references/layers.md。

---

音频与视频

VRC_SpatialAudioSource

为每个世界中的 AudioSource 配置 VRC_SpatialAudioSource：单独的 AudioSource 会触发 VRChat SDK Build Panel 警告。请有意添加配套组件，不要默认盲目使用 Auto Fix，也不要覆盖现有的 VRC_SpatialAudioSource 值或经过调校的 AudioSource 曲线，除非用户有此要求。

属性	说明	基准值 / 安全保留说明
Gain	音量增益（0-24 dB）	10 dB 是常见值/默认值；仅为消除警告而添加时，使用 0 dB 以保留原有响度
Near	衰减起始距离	0m，除非声音需要有意设置近场效果
Far	衰减结束距离	与现有 maxDistance 或预期的可听范围一致；不要盲目使用默认值/Auto Fix 范围
Volumetric Radius	声源扩散范围	点声源设为 0m；宽广声源则有意设置
Enable Spatialization	3D 定位	有意设置为 2D/全局的音频设为 false；制作的 3D 音频设为 true

保留现有 AudioSource 时，请保留 volume、spatialBlend、rolloffMode、maxDistance 和自定义曲线；Gain 使用 0 dB；对于经过调校的 3D 衰减，启用 Use AudioSource Volume Curve；Far 与现有 maxDistance 或预期的可听范围一致；除非现有 minDistance/Near 值是有意设置的，否则 Near 保持为 0m。

Video Player Selection

功能	AVPro	Unity Video
直播流	✅	❌
编辑器预览	❌	✅
YouTube/Twitch	✅	❌
Quest 支持	✅	✅

必须阅读 references/audio-video.md，了解 VRC_SpatialAudioSource 或视频播放器配置。 可选阅读：连接音频/视频组件时，阅读 references/components.md。 不要加载：references/lighting.md、references/performance.md。

---

世界上传

上传步骤

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

上传前检查清单

□ 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

运行 Build & Upload 前，必须阅读 references/upload.md。请先确认上传前检查清单中的所有项目。 当用户询问 SDK Build Panel 验证、红色/黄色/白色警告、Auto Fix 或复制的验证消息时，必须阅读 references/build-validation.md。 不要加载：references/audio-video.md、references/lighting.md。

---

故障排除

快速路由

确定症状类别，然后跳转到对应的参考章节：

症状类别	常见原因	参考
玩家穿过墙壁／地板	未运行图层设置；几何体未设置为 Environment (11)	troubleshooting.md §Layer & Collision
无法抓取／拾取无效	缺少 Collider、Rigidbody 或 VRC_Pickup 组件	troubleshooting.md §Component
对象不同步／弹回原位	缺少 VRC_ObjectSync 或所有权未转移	troubleshooting.md §Networking
无法坐下／穿过 Station	缺少 Collider；需要调整 Station Enter Player Location	troubleshooting.md §Component
镜子没有反射	图层遮罩缺少 Player/PlayerLocal/MirrorReflection	troubleshooting.md §Component
构建／上传失败	缺少 SceneDescriptor、脚本错误、图层警告	troubleshooting.md §Build
性能问题	Mirror 已开启、实时灯光、光照贴图未烘焙	performance.md
在编辑器中正常，但在 VRChat 中失败	编辑器 Play ≠ SDK 运行时；请使用 Build & Test	troubleshooting.md §Editor
UI 可见但无法点击	VRC_UIShape 位于 Screen Space / Overlay Canvas 上（参见 NEVER #11）	troubleshooting.md §Editor

必须阅读 references/troubleshooting.md，以诊断任何问题。对于非故障排查任务，请勿加载。

---

相关技能

对于 C# 脚本、网络同步和 UdonSharp 事件实现，请使用 unity-vrc-udon-sharp 技能。

---

模板（assets/templates/）

用于常见 SDK 组件模式的入门模板。仓库检查涵盖静态检查；使用前请将模板导入目标 SDK 项目，编译并运行 Build & Test。请调整 Inspector 字段，并扩展事件存根以适配你的世界。

模板	用途
VRC_Pickup_Rigidbody.cs	带 Rigidbody 的 VRC_Pickup——OnPickup/OnDrop/OnPickupUseDown/OnPickupUseUp 事件、所有权转移、音频反馈
VRC_Station_Basic.cs	VRC_Station 控制器——OnStationEntered/OnStationExited 事件、PlayerMobility、强制弹出 API

参考资料

文件	内容	约行数
references/components.md	所有组件详情、组件白名单、Dynamics for Worlds、仅限编辑器的排除项（EditorOnly 标签 / IEditorOnly）	800+
references/layers.md	层与碰撞	230+
references/performance.md	性能优化	700+
references/lighting.md	光照设置	400+
references/audio-video.md	音频与视频	600+
references/build-validation.md	SDK 3.10.5 Build Panel 红色 / 黄色 / 白色验证警报目录、安全修复、Auto Fix 副作用	180+
references/upload.md	上传流程	300+
references/troubleshooting.md	故障排除指南	500+
CHEATSHEET.md	快速参考	200+