14. 走进去,事情发生了
本章实现「跨进咖啡厅区域开始播背景音乐,离开区域停止」。播放只影响进入区域的玩家,音乐在区域内不随玩家与 AudioSource 的距离变化。
区域使用勾选 Is Trigger 的 Collider。脚本接收玩家进入、离开事件,并调用 AudioSource.Play() / Stop()。本例立即开始或停止,不包含淡入淡出。
三种不同的音乐需求
Section titled “三种不同的音乐需求”| 需求 | 播放控制 | 声音设置 | 玩家听到什么 |
|---|---|---|---|
| 进入世界就播放的全局 2D BGM | Play On Awake 开,Loop 开,不需要 Trigger | Spatial Blend = 0,关闭空间化 | 音频开始播放后,不因玩家位置改变方向或距离音量 |
| 跨区域才开始/停止的本地 2D BGM(本章) | Play On Awake 关,Trigger 事件调用 Play / Stop,过滤本地玩家 | Spatial Blend = 0,关闭空间化 | 区域内播放,区域外停止,区域内走动不改变空间定位 |
| 固定室内声源持续播放的 3D 音乐 | 独立 AudioSource,Play On Awake 开、Loop 开,不由区域脚本开关 | Spatial Blend = 1,启用并配置空间化/衰减 | 声源固定,玩家移动或转头时,相对方向与距离改变;室外也可能听到 |
Trigger 决定何时播放,Spatial Blend 决定是否按空间位置处理声音。 二者可以分别配置。把 AudioSource 放在屋内,不会让 2D 音乐自动局限在屋内;把它设为 3D,也不会自动按房间边界静音。
本章只把第二种方案接入 MusicZone 脚本。第三种是独立需求,不能同时把它当作本章的播放预期。
Trigger 的作用和事件条件
Section titled “Trigger 的作用和事件条件”普通 Collider 可参与实体碰撞;勾选 Is Trigger 后,该 Collider 用于重叠检测,不再靠它挡住玩家或刚体。墙和区域可以分别使用两个 Collider:墙负责阻挡,区域负责检测。
VRChat 的 OnPlayerTriggerEnter 检测的是玩家胶囊体进入 Trigger,OnPlayerTriggerExit 检测离开,不是 Avatar 某根手指或头部模型是否越界。脚本和区域 Collider 放在同一个启用的 GameObject 上,并确保对象与碰撞层配置允许检测玩家。官方玩家碰撞文档给出的玩家区域设置不要求作者再给这块静止区域添加 Rigidbody。
如果 Is Trigger 未勾选,当前 Collider 就不提供这组 Trigger 进入/离开事件。普通 Collider 的碰撞回调是另一套条件,不能把方法名互换后当作同一种行为。
第一步:划定音乐区域
Section titled “第一步:划定音乐区域”在 Hierarchy 新建空 GameObject,命名 MusicZone,例如设置:
Position 2.5, 1.1, 2.5Rotation 0, 0, 0Scale 1, 1, 1添加 Box Collider,勾选 Is Trigger,设置 Size = 3, 2.2, 3。在 Scene 视图中调整绿色线框,让它覆盖需要播放音乐的整块空间,而不只是门口一条窄带。
这是因为 Exit 对应「离开 Collider」,不是「走出建筑」。如果只在门槛放一条薄 Trigger,玩家穿过门槛进入室内时就已经离开了这条 Trigger,音乐会随即停止。用覆盖室内的体积,才能让其边界与开始/停止位置一致。
Scene 中的 Collider 线框不在游戏内显示。初次测试可另放地面标记表示范围;出生点放在区域外,从外面走入进行测试。本例使用单个区域 Collider,且不处理重叠区域的音乐优先级。
第二步:配置 2D 音乐
Section titled “第二步:配置 2D 音乐”在 MusicZone 添加 Audio Source,将有权使用的音频导入 Assets/Audio/,再拖入 AudioClip。选择循环接缝适合重复播放的音频,长度不决定它能否循环。
AudioClip MyCafeLoopPlay On Awake 关闭Loop 开启Volume 0.6(按音源实际响度调整)Spatial Blend 0(完全 2D)Play On Awake 关闭,场景加载不会由该选项自动开播;Loop 让音频到末尾后继续循环。
如果 AudioSource 上有 VRC Spatial Audio Source,还要关闭其空间化开关。在本轮核对的 Worlds SDK 3.10.5 中,展开 Advanced Options,取消 Enable Spatialization。官方网页的「Using 2D Audio」段使用 Use Spatialized Audio 这一名称;当前 Inspector 以 SDK 的实际字段为准。仅关闭空间化而保留 Spatial Blend = 1,仍可能留下距离衰减。纯 2D 设置需要两处一致。官方配置说明
音乐区的 AudioSource Transform 放在区内便于整理,但在这个 2D 设置下,它的位置不决定左右方向和距离音量。响度仍受素材、Volume、混音和玩家音量设置影响。
第三步:连接进入与离开事件
Section titled “第三步:连接进入与离开事件”在 Assets/Scripts/ 新建 U# Script MusicZone:
using UdonSharp;using UnityEngine;using VRC.SDKBase;
public class MusicZone : UdonSharpBehaviour{ public AudioSource musicSource;
public override void OnPlayerTriggerEnter(VRCPlayerApi player) { if (!Utilities.IsValid(player) || !player.isLocal) return; if (musicSource == null) return;
if (!musicSource.isPlaying) { musicSource.Play(); } }
public override void OnPlayerTriggerExit(VRCPlayerApi player) { if (!Utilities.IsValid(player) || !player.isLocal) return; if (musicSource == null) return;
musicSource.Stop(); }}把脚本挂到 MusicZone,将它的 AudioSource 拖到 Music Source 引用槽。
VRCPlayerApi player表示本次触发对应的玩家。Utilities.IsValid(player)先检查玩家引用;player.isLocal再判断是否为当前客户端的玩家。musicSource == null时直接返回,避免访问未配置的引用。isPlaying防止仍在播放时再次调用Play()。Stop()停止并重置播放位置,所以重新进入时从头播放。本例不是离开暂停、回来续播。
为什么过滤本地玩家
Section titled “为什么过滤本地玩家”客户端可能检测到本地玩家或远端玩家与区域的接触。玩家 Trigger 回调是在各客户端根据自己所见的位置运行的检测,不是脚本自动向网络广播了一条「播放音乐」指令,也不能保证所有客户端同一时刻都检测到同一个边界。
如果 A 进入区域,而 B 的客户端检测到 A 进入,B 上收到的参数代表 A。没有 isLocal 条件时,B 也可能执行本地的 Play(),即使 B 站在区外。加上过滤后,B 会跳过 A 对应的事件;只有 B 自己进入时才播放 B 的音乐。
本例既不共享播放状态,也不对齐各人的歌曲时间。A、B 在不同时间进入,可以听到不同进度。
第四步:Build & Test
Section titled “第四步:Build & Test”保存场景,在 SDK Builder 运行 Build & Test:
- 从区域外出生,应没有这段音乐。
- 从外面步行进入,音乐开始。
- 在区域内从一侧走到另一侧并转头,音乐不应因为与
MusicZone的距离或相对朝向变化而变大、变小或转移方向。 - 走出整个区域,音乐立即停止。
- 再进入,音乐从头播放。
若进行双客户端测试,A 在区内而 B 在区外时,只有 A 应听到这段音乐。单客户端 Build & Test 不能验证这个多人情形;需使用支持多客户端的测试配置分别观察。
排查不符合预期的结果
Section titled “排查不符合预期的结果”- 出生就播放:检查是否仍开着
Play On Awake,或有其他脚本、其他 AudioSource 在播放。 - 进区无声:检查 Collider / GameObject / Udon Behaviour 是否启用、
Is Trigger是否勾选、程序是否编译,以及引用、AudioClip、Mute、Volume 和客户端音量。 - 走过门槛响一下就停:检查 Collider 是否只覆盖薄门槛,扩大为实际音乐区域。
- 区内靠近才听到、转头方向变化:检查是否仍为 3D 或开启了空间化;本例应使用
Spatial Blend = 0。 - 引用为空却没有报错:示例会返回,需在 Inspector 中补上
Music Source。
独立方案:固定位置持续播放的 3D 声源
Section titled “独立方案:固定位置持续播放的 3D 声源”如果需求是「吧台的收音机一直播放,人走出店外仍可能听到」,新建独立物体 CafeSpeaker,不要把它填入本章 Music Source:
- 把
CafeSpeaker放在收音机或音箱的实际位置。 - 添加 AudioSource,设置 AudioClip、
Play On Awake和Loop,Spatial Blend = 1。 - 添加并配置
VRC Spatial Audio Source的空间化与距离衰减。 - 从不同位置靠近、远离并转头试听,调整实际需要的可听范围。
声源始终在 CafeSpeaker 的位置。玩家走到它的左侧、右侧或背后时,改变的是声源相对于听者的方向和距离,不是声音在场景中换了发出位置。
距离音量由使用的衰减曲线决定。在 Worlds SDK 3.10.5 的 Advanced Options 中开启 Enable Spatialization,关闭 Use AudioSource Volume Curve 时使用空间化器的默认衰减,再检查 Near / Far。若开启 Use AudioSource Volume Curve,则检查 AudioSource 自身的曲线与 Min/Max Distance,不能把任意曲线下的 Max Distance 都当作硬静音边界。官方网页还保留 Use Spatializer Falloff 的表述,但该版本 Inspector 没有这个名称的复选框。需要能近距离走到音箱旁时,保留 Volumetric Radius = 0,避免把扩大体积误当作室内范围设置。
墙体不会因有 Collider 就自动隔音。距离衰减和空间化也不会识别「店内/店外」区域;若需要墙后变闷或离开房间完全静音,应明确实现遮挡、滤波或区域控制,并分别测试。
把区域事件用于其他动作
Section titled “把区域事件用于其他动作”进入开灯,离开关灯
Section titled “进入开灯,离开关灯”新建 U# Script AreaLightZone,挂到一个独立的 Box Trigger 上,将目标实时灯拖入 Area Light。灯可以放在区域物体之外;区域控制器保持启用。
using UdonSharp;using UnityEngine;using VRC.SDKBase;
public class AreaLightZone : UdonSharpBehaviour{ public Light areaLight;
private void Start() { if (areaLight != null) areaLight.enabled = false; }
public override void OnPlayerTriggerEnter(VRCPlayerApi player) { if (!Utilities.IsValid(player) || !player.isLocal) return; if (areaLight != null) areaLight.enabled = true; }
public override void OnPlayerTriggerExit(VRCPlayerApi player) { if (!Utilities.IsValid(player) || !player.isLocal) return; if (areaLight != null) areaLight.enabled = false; }}从区外开始 Build & Test,检查初始关闭、进入开启、离开关闭。与音乐合用时,在同一对回调中加入动作即可;同一个类不能重复声明两份 OnPlayerTriggerEnter。
进入时显示提示,离开后保留
Section titled “进入时显示提示,离开后保留”以下变体每次进入都启用提示,没有离开隐藏或定时隐藏行为。新建 HintOnEnter,挂到启用的 Trigger 物体;把另一物体上的提示根节点拖入 Hint,并在编辑器中将提示根节点设为关闭。可先用一个命名为 HintMarker 的可见 Cube 检查显隐,再换为已配置好的 UI。
using UdonSharp;using UnityEngine;using VRC.SDKBase;
public class HintOnEnter : UdonSharpBehaviour{ public GameObject hint;
public override void OnPlayerTriggerEnter(VRCPlayerApi player) { if (!Utilities.IsValid(player) || !player.isLocal) return; if (hint != null) hint.SetActive(true); }}Build & Test 时,区外出生看不到提示,进入后出现,离开后仍保留。不要把控制器放进被关闭的 Hint 层级,否则它也会失去触发入口。需要离开隐藏时,在同一类补 OnPlayerTriggerExit,使用相同身份检查后调用 hint.SetActive(false);需要定时隐藏时,可采用 HintPopup 的完整实现。这些方案的消失条件不同。
返回安全点的区域
Section titled “返回安全点的区域”区域传送的完整脚本与接线已经包含 Transform destination、本地玩家检查和 TeleportTo。用它制作下方回收区时:
- 在正常活动地面下方新建
RecoveryZone,添加有一定厚度的 Box Trigger,覆盖预期落下的范围。 - 把
Teleporter挂在 RecoveryZone,另建SafePoint,放在有地板、无障碍物、远离回收区的位置,将其拖入Destination。 - 在测试场景副本中从边缘落入区域,检查到达 SafePoint 后能站稳、能正常走动,不会反复触发。
- 在 Scene Descriptor 配置并测试
Respawn Height Y作为跌出世界的恢复条件;让有效地面和安全点都位于该高度之上。它使用世界出生点规则,不等同于这个自定义 SafePoint。
回收 Trigger 仍可能漏掉瞬移或高速坠落,不能单独作为可靠防坠落保证。还需单独测试跳跃、较高处落下、Respawn 以及世界允许的移动方式。Scene Descriptor 的重生高度说明
可选用途练习
Section titled “可选用途练习”- 展品讲解:复制 MusicZone 的独立练习对象,改用有权使用的解说音频,关闭 Loop,保持 2D 与本地过滤;进入播放、离开停止、再次进入从头播放。测试音频自然结束后,在区内停留不会自行重播
- 终点区域:用
bool finished记录是否完成;Enter 中先检查本地玩家与finished,首次进入才记录完成时间,重置时清除标记。测试来回跨线不会重复结算;多人计分需要独立的权威核验 - 区域内周期扣分:使用本地
int health = 10与float nextTick,进入时把 nextTick 设为Time.time + 1f;Stay 中仅在本地玩家且Time.time >= nextTick时减一,再设下次时间。记录时间与数值,比较停留约三秒、立即离开、重新进入的结果。这是本地计时练习,不是每次 Stay 都扣一分,也不补算漏掉的秒数
相关事件的区别
Section titled “相关事件的区别”OnPlayerTriggerEnter / Exit:玩家胶囊体进入/离开 Trigger。OnPlayerTriggerStay:玩家仍在 Trigger 内时持续调用;做周期动作时需计时,不能把每次回调当成一秒。OnPlayerCollisionEnter / Stay / Exit:移动物理对象与玩家的接触事件。官方明确指出,玩家单纯走向静止对象不会触发这组回调,区域检测应使用 Trigger。OnTriggerEnter / Exit:普通物理对象的 Unity Trigger 回调,参数是 Collider,不是VRCPlayerApi。它还受刚体和碰撞矩阵条件限制,不能直接替代玩家事件。
- 在音乐的同一对 Enter/Exit 事件中加入灯光开关,测试本地身份过滤是否同时作用于两个动作。
- 把 Box Collider 换成 Sphere Collider,比较开始和停止的位置。改变的是触发区域,不是 2D 声音的方向或衰减。
- 使用下面的计数练习,比较本地过滤前后的回调与状态
观察进入与离开计数
Section titled “观察进入与离开计数”新建 ZoneCounterProbe,挂到独立启用的单个 Box Trigger。它记录收到的进入减离开次数,不修改音乐区脚本。
using UdonSharp;using UnityEngine;using VRC.SDKBase;
public class ZoneCounterProbe : UdonSharpBehaviour{ public bool localOnly = true; private int playersInside;
public override void OnPlayerTriggerEnter(VRCPlayerApi player) { if (!Utilities.IsValid(player)) return; if (localOnly && !player.isLocal) return; playersInside++; Debug.Log("Enter id=" + player.playerId + " local=" + player.isLocal + " count=" + playersInside); }
public override void OnPlayerTriggerExit(VRCPlayerApi player) { if (!Utilities.IsValid(player)) return; if (localOnly && !player.isLocal) return; playersInside--; Debug.Log("Exit id=" + player.playerId + " local=" + player.isLocal + " count=" + playersInside); }}- Local Only 开启,从区外步行进入再离开,日志计数应按收到的回调从 0 到 1 再到 0。
- 重新开始测试,关闭 Local Only,在双客户端中让 A、B 依次进出。每个客户端分别记录收到的 playerId、isLocal 与计数,不假定两边同一帧收到事件。
- ClientSim 运行时查 Unity Console;Build & Test 运行时查对应客户端日志,路径见 客户端日志定位。外部 VRChat 进程的字段不会自动显示在编辑器 Inspector。
- 在区域内退出实例、瞬移进出或禁用区域,记录加减是否失配。简单计数没有 playerId 去重、离开实例清理或位置重新核对,可能成为负数或残留旧值,不能当作可靠实时人数。
区域音乐的组成
Section titled “区域音乐的组成”区域 Collider 定义边界,玩家事件报告进出,isLocal 选择本机玩家,AudioSource 引用确定播放对象,Play / Stop 控制时机。纯 2D 配置使音乐不随听者的场景位置空间化;局部播放来自触发逻辑,而不是距离衰减。
- VRChat Creator Docs:Player Collisions
- VRChat Creator Docs:Player API
- VRChat Creator Docs:VRC Spatial Audio Source
- Unity Manual:Audio Source(2022.3)
- Unity Manual:Introduction to collision(2022.3)
字段名称另按 VRChat 官方 Worlds SDK 3.10.5 包中的 Editor/VRCSDK/SDK3/Components3/VRCSpatialAudioSourceEditor3.cs 核对。这里是源码核对,不代表本教程已在该 SDK 中完成客户端实测。