跳转到内容

附录 C · SDK 与 Unity 组件速查

约 11 分钟

每个组件给出:是什么、关键字段、典型用法、官方文档链接。深度解释回各自章节。

字段以当前 SDK / Unity 2022.3 LTS 的 Inspector 显示为准。SDK 升级后新增 / 删除字段时,以官方 SDK Components 文档 当前页面为准。


描述世界出生点、相机设置和重生高度的 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 RespawnPickup 掉到重生高度以下时的处理: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 MethodContinuous / Manual / None,详见 第 28 章

典型用法(脚本里):

public override void Interact()
{
// 玩家对物体发起 Interact 时触发
}

UdonSharp 的签名写成 public override void Interact()。组件、物体与 Collider 必须启用,并满足距离及交互检测条件。本书按钮使用同一 GameObject 上的非 Trigger Collider。提示可直接写双语;动态语言选择需要作者提供对应文本和切换逻辑。

首次出现:第 7 章、详细字段在 第 13 章。
官方文档:Udon。


让物体可被玩家拿起。默认是本地行为,配 VRC Object Sync 才能让所有人看到。

关键字段作用 / 默认值
Interaction Text指向时的提示文字;留空显示默认标签,自定义文本不自动翻译
Use TextAuto Hold 启用后,持握时显示的使用提示文字
Pickupable是否允许拿起(默认 True,临时锁定时改 False)
Proximity可拿取距离,米,默认 2
Orientation握持姿势:Any / Grip / Gun
Exact Gun / Exact GripOrientation = 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。


在客户端间同步位置、旋转,以及 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。


为同一物体上的 Unity Audio Source 配置 VRChat 空间化与距离衰减;它不替代音频播放组件,也不负责区域进出检测。

关键字段默认值 / 范围作用
Gain世界默认 10 dB,范围 0–24 dB额外增益;10 dB 的上限限制针对头像音源
Far40 m启用空间化衰减时衰减至静音的远距离;按场景范围测试
Near0 m满音量距离,通常保持 0
Volumetric Radius0 m扩大声源的表观体积;必须小于 Far,近距离聆听保留 0 并测试
Use AudioSource Volume CurveFalse空间化启用时,关闭本项用默认衰减;启用本项用 AudioSource 曲线
Enable SpatializationTrue关闭空间化还不够: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。


渲染镜面反射,增加相应视角的绘制开销;具体成本取决于反射内容和分辨率。

关键字段默认值作用
m_DisablePixelLightsFalse启用时将实时逐像素点光和聚光降为顶点光照
m_ReflectLayersEverything反射图层;只需头像时包含 Player 与 MirrorReflection,后者是镜中的本地玩家层
m_TextureSize1024每眼反射分辨率;提高会增加渲染成本,应在目标设备上测试
Custom SkyboxNone反射用的天空盒覆盖

本书示例默认关闭镜子并提供开关。组件需要同物体上的 Mesh Renderer;可从 SDK 的 VRCMirror Prefab 开始配置,确认镜面朝向和反射图层。

首次出现:第 7 章、详细 第 16 章。
官方文档:VRC Mirror Reflection。


让物体能被坐下(椅子、沙发、驾驶座)。会接管玩家移动控制。

关键字段默认值作用
Player MobilityImmobilizeMobile / Immobilize / Immobilize For Vehicle
Can Use Station From StationFalse是否允许从一把椅子直接换到另一把
Disable Station ExitFalse禁用常规离开操作;启用时需提供明确的离开方式
Animation ControllerNoneOverride Controller,用来给坐姿动画
Station Enter Player Location(需手动拖)坐下时玩家落点 Transform。Y 抬到坐姿高度,否则脚穿地
Station Exit Player LocationNone起身时玩家落点;空 = 在 Enter 附近起身
SeatedTrue是否给坐姿(False 用于驾驶 / 站立平台)

挂载条件:Collider 必须在同 GameObject 上(子物体上的 Collider 不算)。事件:OnStationEntered(VRCPlayerApi) / OnStationExited(VRCPlayerApi),所有客户端都会收到,按需 if (!player.isLocal) return;。

首次出现:第 7 章、详细 第 16 章。
官方文档:VRC Station。


把世界 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 世界相关的部分)”

每个 GameObject 自带、删不掉。三个字段:Position、Rotation、Scale。

首次出现:第 6 章 · Transform 与坐标。


形状(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 章。


关键字段作用
TypeDirectional / Point / Spot / Area
Color光色
Intensity亮度
Range照射半径(Point/Spot 用)
Shadows是否投阴影:None / Hard / Soft
ModeRealtime / Mixed / Baked

Directional Light 位置无关,只看 Rotation。三种 Mode 的取舍详见 第 36 章 · 三种 Light Mode。

首次出现:第 7 章、第 9 章 · 光源类型。


保存烘焙光照采样,供支持 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。


某个位置的环境快照,给金属 / 玻璃反射用。不放则金属反射的是 Skybox 而不是房间内饰。

关键字段默认值作用
TypeBaked静态环境用 Baked;实时更新需要另计性能成本
Importance1多个 Probe 重叠时的优先级
Box ProjectionFalse室内盒状空间可启用,并按空间设置 Box Size;效果取决于材质支持
Box Size—房间边界
Resolution128反射贴图分辨率,调高耗显存

烘焙:Lighting 面板 Generate Lighting 旁边的下拉 → Bake Reflection Probes(也可以跟 Lightmap 一起 Generate Lighting)。每个独立空间放一个,Box Size 各自包房间,过渡区让 Probe 略重叠。

首次出现:第 36 章 · Reflection Probe:环境反射。
官方文档:Unity Manual: Reflection Probe。


关键字段作用
Audio Clip放哪个音频
Play On Awake场景加载时是否自动播
Loop是否循环
Volume总音量(0–1)
Spatial Blend0 不按声源位置做 3D 处理,1 完全使用 3D 设置;不决定何时播放
Doppler Level多普勒效应强度,静止音源设 0

Audio Source 负责播放;VRC Spatial Audio Source 额外配置空间化。播放时机与空间化分别设置,区域触发 2D 音乐不需要随距离衰减。
首次出现:第 7 章、第 33 章。


接收音频的”耳朵”。Unity 默认场景里 Main Camera 自带一个;VRChat 世界里不要自己再挂一个——VRChat 客户端会在玩家头部放置 Listener,多挂会冲突或被忽略。

首次出现:第 33 章 提示。


让物体获得重力 / 物理模拟。VRChat 中谨慎用,物理交互成本不低。配合 VRC Object Sync 同步位姿。

关键字段:Mass、Use Gravity、Is Kinematic、Drag、Angular Drag、Constraints(冻结某个轴的位移 / 旋转)。

首次出现:第 7 章。


状态机驱动动画。开关门、电梯、风扇等平滑运动用它。

挂载流程:选中物体 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 章 · 门、机关和状态。


Unity UI 的根。VRChat 世界里可被 VR 指针交互的 Canvas 必须用 World Space 模式。

关键字段在 VRChat 世界里
Render Mode必须改成 World Space(默认是 Screen Space - Overlay,世界 UI 不能用)
Event CameraWorld 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。


支持 SDF 字体的文字组件,本书 UI 示例使用 TMP。清晰度受字体图集、字号、材质和观看距离影响。

第一次创建会要求 Import TMP Essentials(点一下即可)。

关键字段作用
Font AssetTMP 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。


  • Avatar Pedestal:SDK Components 中的头像展示组件
  • Light Probe Proxy Volume:大型动态 Renderer 的光照采样功能,使用前核对目标平台支持
  • Cloth:布料模拟组件;Android / Quest 不支持,见官方平台限制