28. 告诉别人发生了什么
第 27 章的所有权决定谁负责发布状态。要让灯在不同客户端一致,还需要将开关状态放进同步字段,并在接收后更新本地 Light。
Manual 状态同步的四个部分
Section titled “Manual 状态同步的四个部分”[UdonBehaviourSyncMode(BehaviourSyncMode.Manual)]固定此 Behaviour 的同步模式。[UdonSynced]标记要发送的脚本字段。- Owner 修改字段后调用
RequestSerialization()请求序列化。 - 其他客户端在
OnDeserialization()中将收到的字段应用到表现。
序列化是把字段值编码为网络数据;反序列化是把收到的数据还原为字段。OnDeserialization 不负责让字段本身变成同步字段,它负责示例中的 Light、UI 等表现更新。
using UdonSharp;using UnityEngine;using VRC.SDKBase;
[UdonBehaviourSyncMode(BehaviourSyncMode.Manual)]public class LampToggle : UdonSharpBehaviour{ public Light targetLight;
[UdonSynced] private bool isOn = false;
private void Start() { ApplyState(); }
public override void Interact() { if (!Networking.IsOwner(gameObject)) Networking.SetOwner(Networking.LocalPlayer, gameObject); if (!Networking.IsOwner(gameObject)) return;
isOn = !isOn; RequestSerialization(); ApplyState(); }
public override void OnDeserialization() { ApplyState(); }
private void ApplyState() { if (targetLight != null) targetLight.enabled = isOn; }}将这个版本替换原有 LampToggle.cs 的全部内容,不另建同名类。脚本挂在有普通 Collider 的按钮上,填写 Target Light,确认 Inspector 同步模式为 Manual。Light 使用 Realtime 模式;关闭 Light 不会移除已有的烘焙照明。
本例 isOn 初始为 false,因此 Start 后灯关闭。脚本字段是共享状态,Light 只是本地显示结果。Owner 本机也要调用 ApplyState();不能把它删掉并等待自己的 OnDeserialization 自动更新表现。
双客户端测试与时间线
Section titled “双客户端测试与时间线”两边加载初始关闭状态后:
- Alpha 按一次,获得所有权,
isOn变为 true,本机灯开启。 - 序列化请求按网络调度发送;Beta 收到 true 后执行
ApplyState,灯开启。 - Beta 按一次,获得所有权,
isOn变为 false,本机灯关闭。 - Alpha 收到 false 后关闭自己的灯。
两边达到相同状态,但不保证在同一帧改变。
发起端:Interact → 检查所有权 → 修改 isOn ├→ ApplyState(本地表现) └→ RequestSerialization(请求发送)网络:等待调度与传输接收端:写入 isOn → OnDeserialization → ApplyState延迟取决于网络、同步数据量和发送限速,不应给教程填入固定的 50 ms / 150 ms 时间线。所有权竞争仍需单独测试;本例不保证累计每一次同时点击。
| 现象 | 检查项 |
|---|---|
| 本机变化、远端字段不变 | Owner、UdonSynced、Manual 模式和 RequestSerialization |
| 远端字段变化、灯不变 | OnDeserialization 是否调用 ApplyState、Light 引用 |
| Owner 本机不更新 | Interact 是否应用本地表现 |
| 关灯后墙仍亮 | 是否存在其他灯或烘焙照明 |
| 更新延迟或不连续 | 发送结果、网络拥堵与同时操作 |
Manual 与 Continuous
Section titled “Manual 与 Continuous”Manual 适合开关、棋子位置等离散变化,由脚本请求发送。Continuous 适合高频变化且允许中间值近似的状态;它不是每帧发送,也不保证每一个中间值都到达。
物体位置与旋转可以优先检查 VRC Object Sync 是否满足需求,而不是重复实现已有同步。
Manual 请求也有调度与限速。多次调用 RequestSerialization() 不能当作可靠地保存每一个操作历史;需要每次操作的语义时应单独设计请求、确认或状态版本。
同步门的目标状态
Section titled “同步门的目标状态”沿用本地动画门的 Animator 配置中的 IsOpen bool 参数。另建 SyncedDoorController.cs,用它替换交互物体上的本地 AnimatedDoorController,不让两个脚本同时控制同一 Animator:
using UdonSharp;using UnityEngine;using VRC.SDKBase;
[UdonBehaviourSyncMode(BehaviourSyncMode.Manual)]public class SyncedDoorController : UdonSharpBehaviour{ public Animator doorAnimator; public float animationDuration = 0.5f;
[UdonSynced] private bool isOpen; private float nextLocalInteractTime; private bool displayedIsOpen;
private void Start() { ApplyState(); }
public override void Interact() { if (Time.time < nextLocalInteractTime) return; if (!Networking.IsOwner(gameObject)) Networking.SetOwner(Networking.LocalPlayer, gameObject); if (!Networking.IsOwner(gameObject)) return;
isOpen = !isOpen; RequestSerialization(); ApplyState(); }
public override void OnDeserialization() { ApplyState(); }
private void ApplyState() { if (displayedIsOpen != isOpen) nextLocalInteractTime = Time.time + Mathf.Max(0f, animationDuration); displayedIsOpen = isOpen; if (doorAnimator != null) doorAnimator.SetBool("IsOpen", isOpen); }}把实际 Animator 拖入 Door Animator,确认交互物体有普通 Collider、脚本模式为 Manual。Animation Duration 应覆盖实际剪辑和过渡的持续时间,本例先填 0.5 秒。
同步的是目标状态,不是逐帧动画进度。每台客户端收到字段后通过自己的 Animator 过渡;本机操作和远端真实变化都会设置本机点击冷却,重复同值不会延长冷却。这不是全局锁,也不能防止别人同时按门。A 开门后,B 在自己动画期点击应无效,动画结束后才可再按。
本例初次收到 true 也会从本地姿态过渡。需要初始恢复直接跳终态、并在初始同步前禁止交互时,用门的初始状态恢复版替换同一脚本。
同步字段与数据量
Section titled “同步字段与数据量”可以同步的类型包括 bool、数值、string、Unity 向量与颜色、VRCUrl 及支持类型的一维数组,具体以当前 SDK 文档为准。
不能直接把任意 GameObject、Transform 或自定义对象引用当作网络字段传输。若要表示「选中了哪一个场景物体」,可在两边约定相同数组,用同步 int 作为索引。
按当前 Networking Specs & Tricks:
- Manual 单次序列化上限约
280,496字节 - Continuous 单次约
200字节 - Udon 脚本发送速率约
11 KB/s
这些是会调整的网络规格,不是推荐把字段填满的目标。字符串编码、数组长度和协议开销会影响实际尺寸;可在 OnPostSerialization 的结果中查看 success 与 byteCount。例如两个 16 项 int 数组的元素数据约为 128 字节,实际发送还包含其他字段与开销。
拥堵时 Manual 与 Continuous 的处理不同,不能统一写成「全部丢弃」。检查 Networking.IsClogged、序列化结果和日志;按需要降低频率或精简数据。
可选对照:Continuous 字段插值
Section titled “可选对照:Continuous 字段插值”[UdonSynced(UdonSyncMode.Linear)] 可让支持插值的字段在接收端线性插值。它不是发送频率设置,也不能把 bool 开关变成动画。在 SDK 3.10.5 的 UdonSharp 校验中,Manual 不能使用 Linear / Smooth;因此使用独立的 Continuous 示例,不把插值标记直接贴到上面的 Manual 灯上。
using UdonSharp;using UnityEngine;using VRC.SDKBase;
[UdonBehaviourSyncMode(BehaviourSyncMode.Continuous)]public class SyncedLightIntensity : UdonSharpBehaviour{ public Light targetLight; [UdonSynced(UdonSyncMode.Linear)] private float syncedIntensity;
private void Update() { if (Networking.IsOwner(gameObject)) syncedIntensity = 1f + Mathf.PingPong(Time.time, 3f); if (targetLight != null) targetLight.intensity = syncedIntensity; }}在空物体上挂这个脚本,引用一盏独立的 Realtime Light,确认没有别的脚本改它的强度。Owner 持续计算示例值,Continuous 负责调度发送;接收端在 Update 中应用当前插值值。两次测试保持同一场景、两客户端、Owner 和观察位置,只把字段标记由 Linear 改为 None,记录远端强度变化与发送情况。不能因本机平滑就认定网络端也平滑,后加入与 Owner 离开还需各测一次。字段插值定义见 UdonSharp Attributes。
一次性网络事件
Section titled “一次性网络事件”爆炸音效只需要让当前在场者播放一次,不需要为后加入者重播:
using UdonSharp;using UnityEngine;using VRC.SDK3.UdonNetworkCalling;using VRC.Udon.Common.Interfaces;
[UdonBehaviourSyncMode(BehaviourSyncMode.NoVariableSync)]public class ExplosionButton : UdonSharpBehaviour{ public AudioSource explosionSound; public ParticleSystem explosionEffect;
public override void Interact() { SendCustomNetworkEvent(NetworkEventTarget.All, nameof(PlayExplosion)); }
[NetworkCallable] public void PlayExplosion() { if (explosionSound != null) explosionSound.Play(); if (explosionEffect != null) explosionEffect.Play(); }}挂到一个带普通 Collider 的按钮上;AudioSource 填短音效并取消 Play On Awake、Loop,ParticleSystem 取消 Play On Awake,分别拖入两个引用。任选一种效果也能测试,但留空的引用不会产生反馈。先让两位测试者在场,按一次确认双方各播放一次,再让第三位加入确认不重播。
这个版本使用 SDK 3.8.1+ 引入的 [NetworkCallable]。接收方法需符合官方规则,例如 public、void、不重载。兼容旧代码的不带参数 public 方法仍有旧式调用路径,但新例子显式标记可远程调用的方法。
NoVariableSync 禁用同步变量但允许网络事件;None 不允许 SendCustomNetworkEvent。None 并不禁止普通本地脚本引用调用。
| 目标 | 接收者 |
|---|---|
All | 当前实例中的所有玩家,包括发送者 |
Others | 除发送者外的玩家 |
Owner | 目标对象的 Owner |
Self | 本机,立即执行,不经过远端网络 |
发送到 All 时,本机执行与远端到达时机不同。事件有速率与数据量限制,不应每帧无条件发送。
发给 Owner 的请求
Section titled “发给 Owner 的请求”网络事件也可用来请求 Owner 修改共享状态。下面例子让请求者登记自己的 playerId,Owner 发布最近一次登记的 ID:
using UdonSharp;using UnityEngine;using VRC.SDKBase;using VRC.SDK3.UdonNetworkCalling;using VRC.Udon.Common.Interfaces;
[UdonBehaviourSyncMode(BehaviourSyncMode.Manual)]public class RegistrationRequest : UdonSharpBehaviour{ [UdonSynced] private int lastRegisteredPlayerId;
public override void Interact() { SendCustomNetworkEvent(NetworkEventTarget.Owner, nameof(RegisterCaller)); }
[NetworkCallable] public void RegisterCaller() { if (!Networking.IsOwner(gameObject)) return; VRCPlayerApi caller = NetworkCalling.CallingPlayer; if (!Utilities.IsValid(caller)) return; lastRegisteredPlayerId = caller.playerId; RequestSerialization(); ShowRegistration(); }
public override void OnDeserialization() { ShowRegistration(); }
private void ShowRegistration() { Debug.Log($"[Registration] playerId={lastRegisteredPlayerId}"); }}在 Owner 客户端里,Networking.LocalPlayer 是 Owner 自己;NetworkCalling.CallingPlayer 才是当前网络调用的发送者,脱离网络调用时为 null。不要把请求者传来的任意 ID 当成已验证身份。
较新 SDK 的网络事件也支持最多 8 个受支持类型的参数。发送值与方法签名的类型和顺序必须一致,参数不能有默认值,也不能用 params。例如 SendCustomNetworkEvent(NetworkEventTarget.Owner, nameof(SubmitHit), buttonIndex, roundId) 对应 public void SubmitHit(int buttonIndex, int observedRound);buttonIndex 表示场景按钮索引,observedRound 是请求端看到的回合。Owner 仍需验证范围、当前回合和真实发送者资格,完整请求链见GameManager。
RegistrationRequest 挂到独立的带 Collider 的按钮,使用 Manual 模式。Alpha 先进入、Beta 后按按钮,双方日志应显示 Beta 的 playerId,而不是固定显示 Owner 的 ID。日志字段代表最近一次已处理的登记,不是完整玩家名单;名单与离开清理见玩家槽位。
状态与事件的边界
Section titled “状态与事件的边界”| 需求 | 保存方式 |
|---|---|
| 灯当前开关、门目标状态、分数 | 同步变量 |
| 当前在场者的一次音效或特效 | 网络事件 |
| 玩家要求加入或按下某个按钮 | 发给 Owner 的请求,由 Owner 验证并写同步状态 |
| 后加入者知道累计发生次数 | 同步计数,不靠回放旧事件 |
如果状态变化和音效分别发送,不要假设两条通道的到达顺序固定。音效只做瞬时反馈,共享状态仍以同步字段为准。
All 事件:各客户端作用于自己的玩家
Section titled “All 事件:各客户端作用于自己的玩家”这个受控实验使用一块无遮挡的平地,提前告知参与者会发生轻微上抛,得到所有测试者同意后再触发。不要把它放在世界入口自动执行。每台客户端接收同一事件,但只修改自己客户端的 LocalPlayer:
using UdonSharp;using UnityEngine;using VRC.SDKBase;using VRC.SDK3.UdonNetworkCalling;using VRC.Udon.Common.Interfaces;
[UdonBehaviourSyncMode(BehaviourSyncMode.NoVariableSync)]public class BounceAllButton : UdonSharpBehaviour{ public float upwardSpeed = 2f;
public override void Interact() { SendCustomNetworkEvent(NetworkEventTarget.All, nameof(BounceLocal)); }
[NetworkCallable(maxEventsPerSecond: 1)] public void BounceLocal() { VRCPlayerApi local = Networking.LocalPlayer; if (!Utilities.IsValid(local)) return; Vector3 velocity = local.GetVelocity(); velocity.y = upwardSpeed; local.SetVelocity(velocity); Debug.Log($"[Bounce] localId={local.playerId}, upwardSpeed={upwardSpeed}"); }}挂到带普通 Collider 的测试按钮,提示写明「全员上抛测试」。先保持 Upward Speed=2,两位玩家站在平地,按一次后核对两端日志中的 localId 各不相同。速度值不是高度值,实际高度受重力、碰撞和移动规则影响;从低值实测,不承诺固定升高几米。
在副本中仅把目标 All 改为 Self,重测时应只作用于按按钮的人;再改回 All,确认两位当前玩家各执行一次。让第三位在事件之后加入,确认不会补弹。这组对照说明 All 的分发范围与 LocalPlayer 的本机作用范围是两件事,并没有从一台客户端直接控制远端玩家对象。API 见 Player Positions。
- 为灯增加同步 Color 与 float 强度字段,并统一在 ApplyState 中应用
- 在两个场景副本中保留同一组字段、灯、客户端数和操作节奏,分别用 Manual 与 Continuous;每隔两秒按一次,记录 Owner 的 OnPostSerialization 次数、success、byteCount 和远端收到的值。一次只变同步模式,不把同步模式叫作「广播范围」
- 将 ExplosionButton 的效果改成短提示音,验证两位当前玩家收到、后加入者不补播
- 初始字段值与测试预期一致
- 只有 Owner 发布同步状态
- Owner 本地与远端均应用字段到表现
- 事件的接收方法显式标记,Sync Mode 允许网络事件
- 请求者身份与参数经过验证
- 延迟、重复操作和后加入情况均测试