附录 E · 网络同步决策表
选择同步方案时,先确定以下三项:
- 同步什么——是物体的位姿、一个状态字段,还是一次性事件?
- 谁来改——谁可以发起操作,由当前 Owner 接收请求还是按规则转移所有权?同步状态都由当前 Owner 发布。
- 什么时候打包——持续调度,还是在状态变化后请求发送?
同步方案还需考虑迟到加入、所有权变更、发送频率和带宽限制。
主源:
- 第 26 章 · 你看到的,别人不一定看到 — 网络可见性的基本心智模型
- 第 27 章 · Ownership — 所有权机制
- 第 28 章 · 告诉别人发生了什么 — 同步字段 + 网络事件
- 第 29 章 · 后来的人怎么办 — Late Joiner 处理
- 第 30 章 · 多人小游戏 — 综合案例(Manager 模式)
词条层细节见附录 A · 多人同步:所有权、网络事件、Manager 模式。
E.1 主决策树
Section titled “E.1 主决策树”要让别人也看到这件事?│├─ 物体的位置 / 旋转 / 物理状态│ ││ ├─ 玩家可以拿起来扔│ │ └─→ Rigidbody + VRC Pickup + VRC Object Sync│ │ (三件套,第 15 章)│ ││ └─ 不需要拿起,只是要同步移动│ └─→ VRC Object Sync 单装即可│├─ 一个状态(开/关、计数、当前回合、玩家选择)│ ││ ├─ 状态变化频繁(每帧 / 多帧一次):│ │ └─→ [UdonSynced] 字段│ │ + [UdonBehaviourSyncMode(BehaviourSyncMode.Continuous)]│ │ (Continuous 由网络系统自动调度发送,不保证逐帧传输)│ ││ └─ 状态变化偶发(按一次按钮才变;回合切换时才变):│ └─→ [UdonSynced] 字段│ + [UdonBehaviourSyncMode(BehaviourSyncMode.Manual)]│ + Owner 在改完字段后调一次 RequestSerialization()│ (非 Owner 收到后从 OnDeserialization 里读新值)│├─ 一次性事件(按按钮要让所有人都知道)│ ││ ├─ 不需要"重放给迟到的人":│ │ └─→ SendCustomNetworkEvent(NetworkEventTarget.All, nameof(M))│ ││ └─ 迟到的人也要知道事件发生过:│ └─→ 把"事件发生过"翻译成一个状态字段│ (比如 hasGameStarted = true)│ 按上面"状态"分支处理│├─ 只想让某个特定玩家执行(通常是 Owner)│ └─→ SendCustomNetworkEvent(NetworkEventTarget.Owner, nameof(M))│ 保留当前 Owner,由它验证请求;不必为了发请求先转移所有权│└─ 后加入的人也要看到当前状态(Late Joiner) │ ├─ 状态用 [UdonSynced]: │ └─→ 自动追:迟到玩家加入时会收到 OnDeserialization, │ 仍需在接收回调里更新本地显示 │ └─ 状态靠"事件"维护(之前 SendCustomNetworkEvent 广播过): └─→ 追不上:迟到玩家根本没收到那次事件 需要把持久状态保存为同步字段 无参数广播不会自动携带 Owner 的本地变量每个分支的展开见下面的小节。
E.2 同步什么 · 三种数据形态
Section titled “E.2 同步什么 · 三种数据形态”E.2.1 物体的位姿(位置 / 旋转 / 速度)
Section titled “E.2.1 物体的位姿(位置 / 旋转 / 速度)”| 用什么 | 何时用 | 注意 |
|---|---|---|
VRC Object Sync | 位置、旋转及所支持的物理状态需要同步时使用 | 它本身不让玩家拿——拿要配 VRC Pickup |
VRC Pickup | 玩家可以”拿起”这个物体(手柄抓 / 鼠标点) | 拾取时由 VRChat 按规则转移所有权;放下不会自动交回原 Owner,其他修改仍需核对实际 Owner |
Rigidbody | 上面两者的物理基础 | Is Kinematic 视场景定(自由扔的小球关掉,门 / 抽屉常开) |
回链:第 15 章 · 拿起来,丢出去、第 27 章 · Pickup 的所有权。
E.2.2 一个状态字段(开关、计数、回合、玩家选择)
Section titled “E.2.2 一个状态字段(开关、计数、回合、玩家选择)”using UdonSharp;using UnityEngine;using VRC.SDKBase;
[UdonBehaviourSyncMode(BehaviourSyncMode.Manual)]public class RoundStateExample : UdonSharpBehaviour{ [UdonSynced] public int currentTurn; [UdonSynced] public int scoreA; [UdonSynced] public int scoreB;
private void Start() { ShowState(); }
public override void Interact() { if (!Networking.IsOwner(gameObject) || !Networking.IsNetworkSettled) return; currentTurn++; ShowState(); // 更新 Owner 本地显示 RequestSerialization(); // 打包发出去 }
public override void OnDeserialization() { // 非 Owner 在这里读新值并刷新本地表现 ShowState(); }
private void ShowState() { Debug.Log($"[Round] turn={currentTurn}, A={scoreA}, B={scoreB}"); }}将示例保存为 RoundStateExample.cs,挂到有普通 Collider 的测试按钮。这里只用日志显示字段,scoreA / scoreB 初值保持 0;当前 Owner 按按钮推进回合,其他人按下不改变回合。两端检查 [Round],再让第三人加入确认收到当前值。需要真实计分与 TMP 接线时用完整 GameManager。
- 谁来改:写一行
if (!Networking.IsOwner(gameObject)) return;防御。非 Owner 修改同步字段只影响自己的副本,还可能被 Owner 的同步值覆盖。 - 什么时候打包:
Manual模式下 Owner 改完字段后必须调RequestSerialization(),否则别人不会收到。 - 谁会收到:所有非 Owner 客户端、以及迟到加入的客户端,都会在
OnDeserialization里看到字段最新值。
回链:第 28 章 · Manual 状态同步的四个部分、· 同步字段能装什么。
E.2.3 一次性事件(按下广播)
Section titled “E.2.3 一次性事件(按下广播)”下面的方法是ExplosionButton 完整示例的接收端核心,不是独立脚本:
[NetworkCallable]public void PlayExplosion(){ if (explosionSound != null) explosionSound.Play(); if (explosionEffect != null) explosionEffect.Play();}完整示例包含 using、NoVariableSync、两个 Inspector 引用、Interact 的 All 发送点和两客户端测试;按该处接线后再比较。若用于自己的脚本,方法须满足 NetworkCallable 的签名要求,接收 Behaviour 不能是 None。
- 调用方任意客户端都行(不限 Owner)。
- 所有当前在场的客户端(包括调用者自己)都会执行
PlayExplosion。 - Late Joiner 收不到——这次事件之后才进来的玩家不会被补一份。需要”迟到也要看见”的,把它改造成状态字段。
回链:第 28 章 · 一次性网络事件。
E.3 谁来改 · 所有权(Ownership)
Section titled “E.3 谁来改 · 所有权(Ownership)”E.3.1 Owner 是什么
Section titled “E.3.1 Owner 是什么”每一个挂着 UdonBehaviour 的 GameObject,在 VRChat 服务器那里都登记了”现在哪个玩家是 Owner”:
[UdonSynced]字段以 Owner 那份的值为准。RequestSerialization()只有 Owner 调用才有效。- 接收方在 OnDeserialization 中应用收到的状态;Owner 修改后自行更新本地显示。
- Owner 离开时由 VRChat 重新分配所有权,不应依赖固定接替顺序。
E.3.2 什么时候要 SetOwner
Section titled “E.3.2 什么时候要 SetOwner”| 情况 | 要不要 SetOwner |
|---|---|
VRC Pickup 物体被拿起 | 不用——VRChat 自动转 |
| 玩家按一个按钮,要让”按下那个人”成为 Owner,再由他改字段 | 要:进入按钮处理时先请求 Networking.SetOwner(Networking.LocalPlayer, gameObject),复查 IsOwner 确认成功后再改 [UdonSynced] 字段 + RequestSerialization() |
单 Manager 模式:所有同步状态都集中在一个 GameManager 上 | 看场景:保留当前对象 Owner 并发送操作请求,或按明确规则转移所有权;Master 身份不等于对象 Owner |
| 几个人轮流执行回合 | 不一定转 Owner:可以同步 currentPlayerId,由固定 Owner 检查请求者是否轮到;若玩法采用转移模式,则转移成功后才由新 Owner 写状态 |
E.3.3 Ownership 钩子
Section titled “E.3.3 Ownership 钩子”| 钩子 | 在谁那里跑 | 用来做什么 |
|---|---|---|
OnOwnershipRequest(VRCPlayerApi requester, VRCPlayerApi newOwner) | 请求方与当前 Owner | 判断是否允许转移;两端逻辑需一致 |
OnOwnershipTransferred(VRCPlayerApi player) | 所有客户端 | 转移完成后收到通知,刷新 UI、核对当前状态 |
requester 是发起请求者,newOwner 是拟接管者,不保证是同一人。共享比赛字段驱动拒绝的代码、两个控制按钮和双端验收见共享比赛锁。转移回调已经通知各端,无须只为显示 Owner 再广播一次 All。
回链:拒绝请求与转移回调。
E.4 什么时候打包 · Continuous vs Manual vs NoVariableSync
Section titled “E.4 什么时候打包 · Continuous vs Manual vs NoVariableSync”每个 UdonSharpBehaviour 类上贴一条 [UdonBehaviourSyncMode(...)],决定这个脚本怎么参与同步:
| 模式 | 行为 | 适合什么 |
|---|---|---|
BehaviourSyncMode.Continuous | 网络系统自动调度同步,允许中间状态丢失或近似,不保证每帧发包 | 高频变化的小字段,例如 Pickup 类物体的 holding 状态、跟随玩家位置的指针。需要按传输预算测试 |
BehaviourSyncMode.Manual | Udon 不会自动同步;Owner 必须手动调 RequestSerialization() | 状态变化偶发——按一次按钮才变、一回合才换一次。状态改变后需主动请求发送,实际发送仍受调度与限流影响 |
BehaviourSyncMode.NoVariableSync | 字段完全不同步,但仍然能 SendCustomNetworkEvent | 薄壳脚本:挂在按钮、UI、传感器上,自己不存状态,只把交互转发给某个 Manager。本类不引入同步噪音 |
BehaviourSyncMode.None | 彻底关闭网络功能 | 完全本地的脚本(HUD、本地开关)。不同于 NoVariableSync,连 SendCustomNetworkEvent 也用不了 |
第 30 章的 Manager 使用 Manual,本地 GameButton 与 ResetButton 使用 None,通过普通引用调用 Manager 的方法;网络请求由 Manager 发送和接收。若某个按钮脚本本身需要收发网络事件,才选 NoVariableSync。状态集中在 Manager,便于核对修改与序列化顺序。详见 第 30 章 · 结构与规则。
E.4.1 Continuous vs Manual 的实操判断
Section titled “E.4.1 Continuous vs Manual 的实操判断”按多久变一次?├─ 每帧 / 多帧一次(持续动) → Continuous├─ 几秒一次但不可预测 → Manual(在改动那一刻调 RequestSerialization)└─ 不动,按下按钮才动 → Manual边界判断:
- 字段只在操作后变化时可用 Manual;实际序列化大小包含类型与协议开销,以 OnPostSerialization 结果为准。
- 持续变化的位置与旋转可考虑 VRC Object Sync;其他数据需按含义、频率与大小选择,不能仅凭字节数判断。
E.5 Late Joiner(后来的人怎么办)
Section titled “E.5 Late Joiner(后来的人怎么办)”E.5.1 自动追还是追不上
Section titled “E.5.1 自动追还是追不上”| 机制 | 迟到玩家进来时会不会自动看到 | 原因 |
|---|---|---|
[UdonSynced] 字段 | 会 | 同步系统向加入客户端提供已同步的当前值;接收完成后通过 OnDeserialization 更新本地表现 |
VRC Object Sync 物体的位姿 | 会 | 位置、旋转及对应物理状态由同步组件维护 |
SendCustomNetworkEvent 广播过的事件 | 不会 | 那次广播是即时的,迟到玩家压根没收到 |
一句话总结:状态自动追,事件追不上。
回链:第 29 章 · 状态与历史事件。
E.5.2 修法:把”事件”翻译成”状态”
Section titled “E.5.2 修法:把”事件”翻译成”状态””若只广播一次 StartGame,事件之后加入的玩家不会得到游戏已开始的记录。下面把它改为同步 bool,并在 Owner 本机与接收端应用面板状态:
using UdonSharp;using UnityEngine;using VRC.SDKBase;using VRC.SDK3.UdonNetworkCalling;using VRC.Udon.Common.Interfaces;
[UdonBehaviourSyncMode(BehaviourSyncMode.Manual)]public class GameStartState : UdonSharpBehaviour{ public GameObject startedPanel; [UdonSynced] private bool gameStarted;
private void Start() { ApplyState(); }
public override void Interact() { SendCustomNetworkEvent(NetworkEventTarget.Owner, nameof(StartGame)); }
[NetworkCallable] public void StartGame() { if (!Networking.IsOwner(gameObject) || !Networking.IsNetworkSettled) return; if (!Utilities.IsValid(NetworkCalling.CallingPlayer)) return; gameStarted = true; ApplyState(); RequestSerialization(); }
public override void OnDeserialization() { ApplyState(); }
private void ApplyState() { if (startedPanel != null) startedPanel.SetActive(gameStarted); }}挂到带普通 Collider、始终激活的开始按钮上,另建一个显示「游戏已开始」的面板并拖入 Started Panel。不要把脚本或按钮放在会被关闭的面板下面。等待网络就绪后 A 按开始,A/B 均应显示面板;C 后加入也应显示,不需要再按。加载期间面板可能短暂隐藏,这个例子没有“同步中”提示;需要阻止初始交互与区分首次反馈时参考灯的完整初始化示例。
回链:状态与历史事件。
E.5.3 初始化与重发检查
Section titled “E.5.3 初始化与重发检查”Manual 同步字段的当前值由同步系统提供给后来加入者,一般不必为每次加入额外广播一次事件。若需要在特定操作后重新请求序列化,由当前 Owner 调用 RequestSerialization,并在 OnPostSerialization / 接收方 OnDeserialization 中检查结果。
无参数 SendCustomNetworkEvent(All, ...) 只调用各客户端的方法,既不是定向发送,也不会把 Owner 的普通本地字段复制过去。当前 SDK 的带参数事件仍不保存历史,持续状态应使用同步字段。
回链:门首次恢复终态与后续动画锁、灯首次静默与重复同值处理。
E.6 Manager 模式 · 推荐架构
Section titled “E.6 Manager 模式 · 推荐架构”本书的集中状态示例采用以下结构:
GameManager (1 个,挂在场景里) └ [UdonBehaviourSyncMode(BehaviourSyncMode.Manual)] └ [UdonSynced] 所有跨客户端的状态 └ public 方法(被按钮等薄壳调用) ↓ 在方法里: 1. 本地入口向当前 Owner 发参数请求 2. Owner 检查 CallingPlayer、参数与 roundId 3. 改字段、刷新 Owner 本地表现、RequestSerialization()
GameButton, ResetButton (N 个薄壳) └ [UdonBehaviourSyncMode(BehaviourSyncMode.None)] └ Inspector 里拖一个 GameManager 引用 └ Interact() 里调用 manager._RequestHit(...) / _RequestReset()为什么这样架:
- 同步源唯一:所有
[UdonSynced]字段都在 GameManager 上,调试只盯一个地方。 - 薄壳无同步噪音:按钮、显示器自己不带状态,减少不必要的状态副本。
- 职责清晰:薄壳只管”被按了告诉 Manager”,Manager 检查请求条件后修改状态。
回链:第 30 章 · 结构与规则。
E.7 常见错配的对照
Section titled “E.7 常见错配的对照”| 症状 | 待查原因 | 修法 |
|---|---|---|
| 按下按钮,自己看到效果,别人没看到 | 按钮脚本只改了本地字段,没走网络 | 把字段标 [UdonSynced],改完调 RequestSerialization();或改成 SendCustomNetworkEvent(All, ...) |
| 按下按钮,状态先在自己端变,过一会儿被别人 override 回来 | 改字段的人不是 Owner,他改的值只在本机有效,下一次 Owner 同步过来就盖掉 | 改字段前先 SetOwner(Networking.LocalPlayer, gameObject);或者发 SendCustomNetworkEvent(NetworkEventTarget.Owner, "改字段的方法") 让 Owner 改 |
调了 RequestSerialization 但别人没收到 | 可能不是 Owner,也可能发送尚未完成或失败 | 核对 Owner、Manual、字段声明与 OnPostSerialization 的 success / byteCount,再查接收端 OnDeserialization |
| 状态字段同步上了,但另一边的 UI 没刷新 | 没在 OnDeserialization() 里调刷新 | 把”刷新表现”的代码放进 OnDeserialization |
| 后来加入的人看不到游戏已经开始 | SendCustomNetworkEvent 广播过的事件 Late Joiner 收不到 | 把”游戏已开始”做成 [UdonSynced] bool gameStarted 字段,进 OnDeserialization 时刷 UI |
一个挂 [UdonBehaviourSyncMode(None)] 的脚本调 SendCustomNetworkEvent 没反应 | None 模式连网络事件都关 | 改成 NoVariableSync(保留网络事件,只关字段同步) |
| 网络方法无法调用 | 名称或签名不满足网络入口要求 | 核对 public、void、NetworkCallable、无重载和参数类型;用 nameof(M) 检查拼写 |
E.8 三项机制速查
Section titled “E.8 三项机制速查”检查状态和事件时分别核对:
- 想让别人看到状态:用
[UdonSynced]字段,Owner 改完调RequestSerialization,非 Owner 在OnDeserialization里读。 - 想让当前目标客户端执行一次事件:用
SendCustomNetworkEvent(All, ...)。但 Late Joiner 收不到。 - 操作者需要接管时:请求 SetOwner 并确认成功后再改字段;集中计分时保留当前 Owner,用带身份和回合校验的请求。
- 第 26 章 · 你看到的,别人不一定看到 — 网络可见性基础
- 第 27 章 · Ownership — 所有权机制 +
OnOwnershipRequest/OnOwnershipTransferred - 第 28 章 · 告诉别人发生了什么 —
[UdonSynced]+SendCustomNetworkEvent - 第 29 章 · 后来的人怎么办 — Late Joiner 处理
- 第 30 章 · 多人小游戏 — 综合案例 / Manager 模式
外部参考: