附录 C · SDK 与 Unity 组件速查
每个组件给出:是什么、关键字段、典型用法、官方文档链接。深度解释回各自章节。
字段以当前 SDK / Unity 2022.3 LTS 的 Inspector 显示为准。SDK 升级后新增 / 删除字段时,以官方 SDK Components 文档 当前页面为准。
VRChat SDK 组件
Section titled “VRChat SDK 组件”VRC Scene Descriptor
Section titled “VRC Scene Descriptor”描述世界出生点、相机设置和重生高度的 SDK 组件。每个作为 VRChat 世界构建的场景都需要它。
| 关键字段 | 作用 |
|---|---|
Spawns | 出生点数组。把空物体拖进 Element 0、1、2… |
Spawn Order | 出生点选择策略:First / Sequential / Random / Demo |
Spawn Orientation | 出生朝向:Default / AlignPlayerWithSpawnPoint / AlignRoomWithSpawnPoint |
Reference Camera | 把该相机的相关设置应用到实例中的玩家视图 |
Respawn Height Y | 玩家掉到这个 Y 值以下时自动重生 |
Object Behaviour at Respawn | Pickup 掉到重生高度以下时的处理:Respawn 返回初始位置,Destroy 删除 |
首次出现:第 5 章 · 第四步:添加场景描述组件;出生配置另见第 31 章。
官方文档:VRC Scene Descriptor。
Udon Behaviour(与 UdonSharpBehaviour 脚本)
Section titled “Udon Behaviour(与 UdonSharpBehaviour 脚本)”承载 Udon 程序的组件,程序可由 UdonSharp 或 Udon Graph 生成。Pickup、Station 等 SDK 组件也有独立功能,并非所有交互都依赖自定义 Udon 脚本。
| 关键字段 | 作用 |
|---|---|
Interaction Text | 客户端显示的交互提示文字;例如 开灯 / Light,自定义文字不会自动翻译 |
Proximity | 交互距离参数;VR 按手柄射线到碰撞点计算,桌面端还包含额外伸手距离补偿 |
Sync Method | Continuous / Manual / None,详见 第 28 章 |
典型用法(脚本里):
public override void Interact(){ // 玩家对物体发起 Interact 时触发}UdonSharp 的签名写成 public override void Interact()。组件、物体与 Collider 必须启用,并满足距离及交互检测条件。本书按钮使用同一 GameObject 上的非 Trigger Collider。提示可直接写双语;动态语言选择需要作者提供对应文本和切换逻辑。
首次出现:第 7 章、详细字段在 第 13 章。
官方文档:Udon。
VRC Pickup
Section titled “VRC Pickup”让物体可被玩家拿起。默认是本地行为,配 VRC Object Sync 才能让所有人看到。
| 关键字段 | 作用 / 默认值 |
|---|---|
Interaction Text | 指向时的提示文字;留空显示默认标签,自定义文本不自动翻译 |
Use Text | Auto Hold 启用后,持握时显示的使用提示文字 |
Pickupable | 是否允许拿起(默认 True,临时锁定时改 False) |
Proximity | 可拿取距离,米,默认 2 |
Orientation | 握持姿势:Any / Grip / Gun |
Exact Gun / Exact Grip | Orientation = Gun / Grip 时的对齐 Transform |
Auto Hold | 组件版本 1.1 为复选框;1.0 为 Yes / No / Sometimes / Auto Detect。控制松开 Grab 后是否继续持握 |
Allow Manipulation When Equipped | 是否允许键鼠或手柄玩家调整已持握物体 |
Disallow Theft | 是否禁止他人从你手里抢走(默认 False) |
Throw Velocity Boost Min Speed / Scale | 启用投掷加速所需的最低速度与倍率 |
挂载条件:同一 GameObject 上具有 Collider 和 Rigidbody。本书投掷物使用非 Trigger Collider,使物体参与碰撞。若需要区域检测,另设 Trigger Collider。
事件(在 UdonSharpBehaviour 里写 public override):
public override void OnPickup() { /* 拿起的瞬间 */ }public override void OnDrop() { /* 放下的瞬间 */ }public override void OnPickupUseDown(){ /* 持握时按使用键 */ }public override void OnPickupUseUp() { /* 持握时松使用键 */ }Any 保留自由握持;Gun 按 Exact Gun 固定方向;Grip 的对齐在 VR 与非 VR 中不同。Exact 锚点使用 Pickup 的子 Transform,位置放在预期握点,朝向按官方轴向规则和客户端实际握持结果调整。分别测试桌面、VR 左右手的拿取、使用、释放与重新拿取。
首次出现:第 7 章、详细字段 第 15 章。
官方文档:VRC Pickup。
VRC Object Sync
Section titled “VRC Object Sync”在客户端间同步位置、旋转,以及 Rigidbody 的重力与运动学状态。可与 Pickup 配合使用。
| 关键字段 | 作用 |
|---|---|
Allow Collision Ownership Transfer | 与其他玩家拥有的物体碰撞时,是否允许转移所有权 |
Force Kinematic On Remote | 非 Owner 客户端的 Rigidbody 是否强制为 Kinematic |
SetGravity(bool) / SetKinematic(bool) | 脚本方法:修改并同步对应物理状态 |
需要物理模拟时配置 Rigidbody;拾取和启用的碰撞转移规则影响 Owner。细节 第 27 章 · Ownership。
首次出现:第 7 章、详细 第 15 章。
官方文档:VRC Object Sync。
VRC Spatial Audio Source
Section titled “VRC Spatial Audio Source”为同一物体上的 Unity Audio Source 配置 VRChat 空间化与距离衰减;它不替代音频播放组件,也不负责区域进出检测。
| 关键字段 | 默认值 / 范围 | 作用 |
|---|---|---|
Gain | 世界默认 10 dB,范围 0–24 dB | 额外增益;10 dB 的上限限制针对头像音源 |
Far | 40 m | 启用空间化衰减时衰减至静音的远距离;按场景范围测试 |
Near | 0 m | 满音量距离,通常保持 0 |
Volumetric Radius | 0 m | 扩大声源的表观体积;必须小于 Far,近距离聆听保留 0 并测试 |
Use AudioSource Volume Curve | False | 空间化启用时,关闭本项用默认衰减;启用本项用 AudioSource 曲线 |
Enable Spatialization | True | 关闭空间化还不够:2D 音频同时要求 Audio Source 的 Spatial Blend 为 0 |
Audio Source 配置音频、音量、循环和播放时机。全局 2D BGM 可用 Play On Awake;本书区域 2D BGM 关闭 Play On Awake,由本地玩家的 Trigger 进出调用 Play/Stop,Spatial Blend 为 0 并关闭空间化。独立的固定 3D 声源采用 Spatial Blend 为 1 与空间化衰减;玩家移动改变相对方向和距离,墙体不会因此自动隔音。
首次出现:第 7 章、详细 第 33 章。
官方文档:VRC Spatial Audio Source。
VRC Mirror Reflection
Section titled “VRC Mirror Reflection”渲染镜面反射,增加相应视角的绘制开销;具体成本取决于反射内容和分辨率。
| 关键字段 | 默认值 | 作用 |
|---|---|---|
m_DisablePixelLights | False | 启用时将实时逐像素点光和聚光降为顶点光照 |
m_ReflectLayers | Everything | 反射图层;只需头像时包含 Player 与 MirrorReflection,后者是镜中的本地玩家层 |
m_TextureSize | 1024 | 每眼反射分辨率;提高会增加渲染成本,应在目标设备上测试 |
Custom Skybox | None | 反射用的天空盒覆盖 |
本书示例默认关闭镜子并提供开关。组件需要同物体上的 Mesh Renderer;可从 SDK 的 VRCMirror Prefab 开始配置,确认镜面朝向和反射图层。
首次出现:第 7 章、详细 第 16 章。
官方文档:VRC Mirror Reflection。
VRC Station
Section titled “VRC Station”让物体能被坐下(椅子、沙发、驾驶座)。会接管玩家移动控制。
| 关键字段 | 默认值 | 作用 |
|---|---|---|
Player Mobility | Immobilize | Mobile / Immobilize / Immobilize For Vehicle |
Can Use Station From Station | False | 是否允许从一把椅子直接换到另一把 |
Disable Station Exit | False | 禁用常规离开操作;启用时需提供明确的离开方式 |
Animation Controller | None | Override Controller,用来给坐姿动画 |
Station Enter Player Location | (需手动拖) | 坐下时玩家落点 Transform。Y 抬到坐姿高度,否则脚穿地 |
Station Exit Player Location | None | 起身时玩家落点;空 = 在 Enter 附近起身 |
Seated | True | 是否给坐姿(False 用于驾驶 / 站立平台) |
挂载条件:Collider 必须在同 GameObject 上(子物体上的 Collider 不算)。事件:OnStationEntered(VRCPlayerApi) / OnStationExited(VRCPlayerApi),所有客户端都会收到,按需 if (!player.isLocal) return;。
首次出现:第 7 章、详细 第 16 章。
官方文档:VRC Station。
VRC Portal Marker
Section titled “VRC Portal Marker”把世界 A 接到世界 B。运行时由 VRChat 客户端自动渲染椭圆门 + 预览图,不需要在 Unity 里挂 Mesh / Material。
| 关键字段 | 作用 |
|---|---|
World ID | 目标世界的 World ID,格式 wrld_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
Custom Portal Name | 覆盖传送门顶部显示的名称(留空 = 显示目标世界真实名) |
World | 直连内置位置:None / Home / Hub。选了内置位置就不用填 World ID |
放置后在客户端检查传送门朝向、入口空间和目标世界;以实际可见与可进入的一面为准。
SDK 自带现成 Prefab VRCWorld_PortalMarker,Project 面板搜得到,建议直接用。
首次出现:第 35 章 · 传送门和世界连接。
官方文档:VRC Portal Marker。
Unity 内置组件(与 VRChat 世界相关的部分)
Section titled “Unity 内置组件(与 VRChat 世界相关的部分)”Transform
Section titled “Transform”每个 GameObject 自带、删不掉。三个字段:Position、Rotation、Scale。
首次出现:第 6 章 · Transform 与坐标。
Mesh Filter + Mesh Renderer
Section titled “Mesh Filter + Mesh Renderer”形状(Mesh Filter)和”画出来”(Mesh Renderer)的两件套。关掉 Mesh Renderer 物体隐形,但 Collider 还在。
关键字段:Mesh Renderer 的 Materials(决定外观)、Cast Shadows(投不投影)、Receive Shadows、Light Probes(动态物体取光来源)。
首次出现:第 6 章。
Box Collider / Sphere Collider / Mesh Collider
Section titled “Box Collider / Sphere Collider / Mesh Collider”| 类型 | 形状 | 性能 | 默认挂载 |
|---|---|---|---|
Box Collider | 长方体 | 简单碰撞体 | Cube |
Sphere Collider | 球 | 简单碰撞体 | Sphere |
Capsule Collider | 胶囊 | 简单碰撞体 | Capsule |
Mesh Collider | 网格表面 | 成本受面数与凸性影响 | Plane |
通用字段 Is Trigger:勾上 = 不阻挡只检测;不勾 = 物理阻挡 + 碰撞事件。要用 OnPlayerTriggerEnter 时,Is Trigger 必须勾上(第 14 章)。
形状允许时可用 Box/Sphere 简化碰撞计算。首次出现:第 5 章、第 6 章。
| 关键字段 | 作用 |
|---|---|
Type | Directional / Point / Spot / Area |
Color | 光色 |
Intensity | 亮度 |
Range | 照射半径(Point/Spot 用) |
Shadows | 是否投阴影:None / Hard / Soft |
Mode | Realtime / Mixed / Baked |
Directional Light 位置无关,只看 Rotation。三种 Mode 的取舍详见 第 36 章 · 三种 Light Mode。
首次出现:第 7 章、第 9 章 · 光源类型。
Light Probe Group
Section titled “Light Probe Group”保存烘焙光照采样,供支持 Light Probe 的动态 Renderer 使用,例如头像与可移动 Pickup。
操作流程:Hierarchy 右键 Light → Light Probe Group(默认 8 个 Probe 排立方体)→ Edit Light Probes 进入编辑模式 → 选中 Probe 用 Ctrl+D 复制并拖到位 → 撒满玩家会走的区域。
探针覆盖可移动物体活动的三维范围,在明暗边界和楼梯处增加采样;用可视化和动态测试物体检查插值结果。
烘焙时跟 Lightmap 一起跑(Generate Lighting)。
首次出现:第 36 章 · Light Probe:动态对象的环境光。
官方文档:Unity Manual: Light Probe Group。
Reflection Probe
Section titled “Reflection Probe”某个位置的环境快照,给金属 / 玻璃反射用。不放则金属反射的是 Skybox 而不是房间内饰。
| 关键字段 | 默认值 | 作用 |
|---|---|---|
Type | Baked | 静态环境用 Baked;实时更新需要另计性能成本 |
Importance | 1 | 多个 Probe 重叠时的优先级 |
Box Projection | False | 室内盒状空间可启用,并按空间设置 Box Size;效果取决于材质支持 |
Box Size | — | 房间边界 |
Resolution | 128 | 反射贴图分辨率,调高耗显存 |
烘焙:Lighting 面板 Generate Lighting 旁边的下拉 → Bake Reflection Probes(也可以跟 Lightmap 一起 Generate Lighting)。每个独立空间放一个,Box Size 各自包房间,过渡区让 Probe 略重叠。
首次出现:第 36 章 · Reflection Probe:环境反射。
官方文档:Unity Manual: Reflection Probe。
Audio Source
Section titled “Audio Source”| 关键字段 | 作用 |
|---|---|
Audio Clip | 放哪个音频 |
Play On Awake | 场景加载时是否自动播 |
Loop | 是否循环 |
Volume | 总音量(0–1) |
Spatial Blend | 0 不按声源位置做 3D 处理,1 完全使用 3D 设置;不决定何时播放 |
Doppler Level | 多普勒效应强度,静止音源设 0 |
Audio Source 负责播放;VRC Spatial Audio Source 额外配置空间化。播放时机与空间化分别设置,区域触发 2D 音乐不需要随距离衰减。
首次出现:第 7 章、第 33 章。
Audio Listener
Section titled “Audio Listener”接收音频的”耳朵”。Unity 默认场景里 Main Camera 自带一个;VRChat 世界里不要自己再挂一个——VRChat 客户端会在玩家头部放置 Listener,多挂会冲突或被忽略。
首次出现:第 33 章 提示。
Rigidbody
Section titled “Rigidbody”让物体获得重力 / 物理模拟。VRChat 中谨慎用,物理交互成本不低。配合 VRC Object Sync 同步位姿。
关键字段:Mass、Use Gravity、Is Kinematic、Drag、Angular Drag、Constraints(冻结某个轴的位移 / 旋转)。
首次出现:第 7 章。
Animator
Section titled “Animator”状态机驱动动画。开关门、电梯、风扇等平滑运动用它。
挂载流程:选中物体 Window → Animation → Animation(Ctrl+6)→ 创建第一段 Animation Clip 时 Unity 会自动为该物体加上 Animator 组件并新建一个 Animator Controller。
Animator Controller 内部对象:
| 对象 | 作用 |
|---|---|
| State | 一个动画状态(如 Door_Open / Door_Close),右键 Set as Layer Default State 设默认 |
| Transition | 从一个 State 到另一个的连接,右键 State Make Transition 创建 |
| Parameter | 状态机的输入。Parameters 标签 + 加 Bool / Int / Float / Trigger |
Transition 关键字段:
Has Exit Time:启用时,过渡还需满足动画时间条件;需要立即响应参数变化时关闭。Conditions:触发条件,例如IsOpen == true。
脚本接口:SetBool(name, value) / SetInt / SetFloat / SetTrigger,参数字符串必须与 Controller 中的名称一致;nameof() 只检查 C# 标识符,不能验证 Animator 资产中的参数。
首次出现:第 7 章、详细 第 17 章 · 门、机关和状态。
Canvas
Section titled “Canvas”Unity UI 的根。VRChat 世界里可被 VR 指针交互的 Canvas 必须用 World Space 模式。
| 关键字段 | 在 VRChat 世界里 |
|---|---|
Render Mode | 必须改成 World Space(默认是 Screen Space - Overlay,世界 UI 不能用) |
Event Camera | World Space 时填 Reference Camera |
Sort Order | 多个 Canvas 叠加顺序 |
World Space Canvas 的 1 单位 = 1 米。常见做法:Width = 400 + Scale = 0.005,实际呈现宽度 2 米;UI 元素按大像素布局再整体缩放,实际清晰度还取决于字体、Shader、分辨率与观看距离。
可被指针点击的 UI 还需要 VRC_UIShape 组件挂在同一个 Canvas 上,VRChat 才会派发指针事件。
首次出现:第 34 章 · World Space Canvas 的搭法。
官方文档:Unity Manual: Canvas Render Mode。
TextMeshPro - Text (TMP)
Section titled “TextMeshPro - Text (TMP)”支持 SDF 字体的文字组件,本书 UI 示例使用 TMP。清晰度受字体图集、字号、材质和观看距离影响。
第一次创建会要求 Import TMP Essentials(点一下即可)。
| 关键字段 | 作用 |
|---|---|
Font Asset | TMP SDF 字体资产,决定能显示哪些字符 |
Auto Size + Min/Max | 按内容自动选字号,省去手调 |
Font Size | 字号;World Space + Scale 0.005 时常用 60–120 |
Color / Material Preset | 颜色 / 描边等预设 |
Alignment | 对齐 |
Wrapping / Overflow | 折行 / 溢出策略 |
需要生成中文静态字体图集时:Window → TextMeshPro → Font Asset Creator,配 Source Font File(如 Source Han Sans / 思源黑体)+ Character Set: Custom Characters 把全部要显示的中文字符贴进去 → Generate Font Atlas → Save TextMeshPro Font Asset。缺字时检查字体资产、动态字形设置与已配置的 fallback 字体;都不含该字符时会显示替代字形。
首次出现:第 34 章 · TextMeshPro 与中文字体。
官方文档:TMP Font Asset Creator。
其他组件参考
Section titled “其他组件参考”- Avatar Pedestal:SDK Components 中的头像展示组件
- Light Probe Proxy Volume:大型动态 Renderer 的光照采样功能,使用前核对目标平台支持
- Cloth:布料模拟组件;Android / Quest 不支持,见官方平台限制