30. 做一个多人小游戏
场上有四个按钮,每回合只有一个发光。Owner 接受本回合第一个有效请求后,给请求者加一分并选择另一个按钮。计分板显示当前实例中的玩家和分数。
这里的「第一个」是 Owner 按收到的请求顺序判定,不是测量所有玩家现实中手指动作的先后。网络延迟会影响结果;这是一份用于验证同步机制的小游戏实现。
TapTheLightGame├─ GameManager 空物体 + GameManager.cs├─ Button_0 Cube + Collider + Light + GameButton.cs├─ Button_1 同上├─ Button_2 同上├─ Button_3 同上├─ ResetButton Cube + Collider + ResetButton.cs└─ Scoreboard World Space Canvas + TextMeshProUGUIManager 保存同步数据,按钮只提交本机请求。点击不会反复接管 Manager 所有权,避免多个客户端各自基于旧分数写回。
activeButtonIndex:当前发光按钮roundId:当前回合编号,拒绝延迟到达的旧请求playerIds/scores:并行数组,同一下标代表同一玩家- Owner:处理有效请求并发布状态
- 其他客户端:接收状态并更新按钮与计分板
代码使用 SDK 3.8.1+ 的 NetworkCallable 与带参数网络事件,运行前确认项目 SDK 支持这些 API。
搭场地与 UI
Section titled “搭场地与 UI”将四个 Cube 放在可操作高度,保留普通 Box Collider,不勾 Is Trigger:
Button_0 Position -2, 1, 0 Scale 0.5, 0.3, 0.5Button_1 Position -0.7, 1, 0 Scale 0.5, 0.3, 0.5Button_2 Position 0.7, 1, 0 Scale 0.5, 0.3, 0.5Button_3 Position 2, 1, 0 Scale 0.5, 0.3, 0.5各按钮添加 Point Light,设为 Realtime,Range 2、Intensity 0,关闭不需要的阴影。另建一个 Cube 作为 ResetButton,例如 Position (0, 1, 2)、Scale (0.4, 0.4, 0.4),使用区别于计分按钮的材质。这里的坐标是摆放起点,需在客户端检查能否够到;空物体加材质并不会自动产生可见网格。
创建 Canvas,Render Mode 设为 World Space,例如 Width 600、Height 500、Scale 0.005。添加 TMP 文本,使用包含所需字符的字体,或按官方 TMP 文档配置客户端 fallback。计分板放在不挡按钮的位置,在客户端检查阅读距离。
GameManager
Section titled “GameManager”using UdonSharp;using UnityEngine;using VRC.SDKBase;using VRC.SDK3.UdonNetworkCalling;using VRC.Udon.Common.Interfaces;using TMPro;
[UdonBehaviourSyncMode(BehaviourSyncMode.Manual)]public class GameManager : UdonSharpBehaviour{ private const int MAX_PLAYERS = 16; public GameButton[] buttons; public TextMeshProUGUI scoreboardText; public AudioSource resetSound; public bool useLocalDebounce;
[UdonSynced] private int activeButtonIndex = -1; [UdonSynced] private int roundId; [UdonSynced] private int[] playerIds = new int[MAX_PLAYERS]; [UdonSynced] private int[] scores = new int[MAX_PLAYERS];
private bool ready; private float nextLocalHitTime;
private void Start() { UpdateUI(); if (Networking.IsOwner(gameObject)) _InitializeOwner(); }
public void _InitializeOwner() { if (!Networking.IsOwner(gameObject)) return; if (!Networking.IsNetworkSettled) { SendCustomEventDelayedSeconds(nameof(_InitializeOwner), 0.5f); return; }
ReconcilePlayers(); if (activeButtonIndex < 0) ActivateRandomButton(); ready = true; PublishState(); }
public override void OnDeserialization() { ready = true; UpdateUI(); }
public override void OnOwnershipTransferred(VRCPlayerApi player) { if (Utilities.IsValid(player) && player.isLocal) _InitializeOwner(); }
public override void OnPlayerJoined(VRCPlayerApi player) { UpdateUI(); // 本机已能解析新玩家,即使数组先于加入事件到达也刷新姓名。 if (!Networking.IsOwner(gameObject) || !ready) return; ReconcilePlayers(); PublishState(); }
public override void OnPlayerLeft(VRCPlayerApi player) { UpdateUI(); if (!Networking.IsOwner(gameObject) || !ready) return; int slot = FindSlot(player.playerId); if (slot >= 0) { playerIds[slot] = 0; scores[slot] = 0; } ReconcilePlayers(); PublishState(); }
// 本地按钮入口;下划线避免它被作为旧式无参数网络入口使用。 public void _RequestHit(int buttonIndex) { if (!ready) return; if (useLocalDebounce) { if (Time.time < nextLocalHitTime) return; nextLocalHitTime = Time.time + 0.1f; } SendCustomNetworkEvent(NetworkEventTarget.Owner, nameof(SubmitHit), buttonIndex, roundId); }
[NetworkCallable] public void SubmitHit(int buttonIndex, int observedRound) { if (!Networking.IsOwner(gameObject) || !ready) return; VRCPlayerApi caller = NetworkCalling.CallingPlayer; if (!Utilities.IsValid(caller)) return; if (buttons == null || buttonIndex < 0 || buttonIndex >= buttons.Length) return; if (buttonIndex != activeButtonIndex || observedRound != roundId) return;
int slot = FindSlot(caller.playerId); if (slot < 0) return; // 无计分槽位的玩家观战。
scores[slot]++; roundId++; ActivateRandomButton(); PublishState(); }
public void _RequestReset() { if (!ready) return; SendCustomNetworkEvent(NetworkEventTarget.Owner, nameof(ResetGame)); }
[NetworkCallable] public void ResetGame() { if (!Networking.IsOwner(gameObject) || !ready) return; VRCPlayerApi caller = NetworkCalling.CallingPlayer; if (!Utilities.IsValid(caller)) return; // 有效实例玩家均可重置,包括观战者。
for (int i = 0; i < scores.Length; i++) scores[i] = 0; roundId++; // 使重置前尚未到达的点击请求失效。 ActivateRandomButton(); PublishState(); SendCustomNetworkEvent(NetworkEventTarget.All, nameof(PlayResetEffect)); }
[NetworkCallable] public void PlayResetEffect() { if (resetSound != null) resetSound.Play(); Debug.Log("[Game] Reset effect"); }
private void PublishState() { RequestSerialization(); UpdateUI(); }
private void ReconcilePlayers() { for (int i = 0; i < playerIds.Length; i++) { if (playerIds[i] == 0) continue; if (!Utilities.IsValid(VRCPlayerApi.GetPlayerById(playerIds[i]))) { playerIds[i] = 0; scores[i] = 0; } }
VRCPlayerApi[] current = new VRCPlayerApi[VRCPlayerApi.GetPlayerCount()]; VRCPlayerApi.GetPlayers(current); for (int i = 0; i < current.Length; i++) { VRCPlayerApi player = current[i]; if (!Utilities.IsValid(player) || FindSlot(player.playerId) >= 0) continue; int slot = FindEmptySlot(); if (slot < 0) break; playerIds[slot] = player.playerId; scores[slot] = 0; } }
private void ActivateRandomButton() { if (buttons == null || buttons.Length == 0) { activeButtonIndex = -1; return; }
if (buttons.Length == 1) { activeButtonIndex = 0; return; }
if (activeButtonIndex < 0 || activeButtonIndex >= buttons.Length) { activeButtonIndex = Random.Range(0, buttons.Length); return; }
int next = Random.Range(0, buttons.Length - 1); if (next >= activeButtonIndex) next++; activeButtonIndex = next; }
private int FindSlot(int playerId) { for (int i = 0; i < playerIds.Length; i++) if (playerIds[i] == playerId) return i; return -1; }
private int FindEmptySlot() { for (int i = 0; i < playerIds.Length; i++) if (playerIds[i] == 0) return i; return -1; }
private void UpdateUI() { if (buttons != null) { for (int i = 0; i < buttons.Length; i++) if (buttons[i] != null) buttons[i].SetGlowing(ready && i == activeButtonIndex); }
if (scoreboardText == null) return; if (!ready) { scoreboardText.text = "同步中 / Synchronizing"; return; }
string text = "Scoreboard / 计分板\n\n"; for (int i = 0; i < playerIds.Length; i++) { if (playerIds[i] == 0) continue; VRCPlayerApi player = VRCPlayerApi.GetPlayerById(playerIds[i]); string name = Utilities.IsValid(player) ? player.displayName : "(offline)"; text += $"{name}: {scores[i]}\n"; } scoreboardText.text = text; }}各部分的责任
Section titled “各部分的责任”ready是本地标记;初始同步前不发点击请求。_InitializeOwner等待网络就绪,核对在线名单;接管时保留已有分数,不重置整局。SubmitHit使用CallingPlayer识别请求者,不能使用 Owner 的 LocalPlayer 给请求者计分。observedRound与当前roundId必须一致。一次计分后 roundId 改变,同回合的其他请求失效。ActivateRandomButton在剩余索引中随机选择,避免把重复结果固定挪到下一个按钮造成偏差。PublishState同时请求网络发送与刷新 Owner 本地 UI。- 玩家加入/离开时所有客户端都刷新 UI,只有 Owner 修改数组;这样同步字段先到、玩家对象后到时,姓名也能更新。
ReconcilePlayers在初始化、加入、离开和接管时核对名单,避免仅靠某个固定事件顺序清理旧 Owner。
本例最多 16 个计分槽位,0 表示空位;满员时其余玩家观战。playerId 是实例内标识,不用于跨实例存档。名单调和不规定观战者进入空位的竞争优先级;需要排队规则时,应明确保存队列。
另一种数据结构是增加与 playerIds 等长的 bool[] slotOccupied 来表示占用,适用于业务 ID 允许等于空值标记的设计。采用它时,查空位、加入、离开、接管核对都必须同步维护该数组;本例直接以 0 表示空槽,避免多维护一份占用状态。
PlayResetEffect 只控制短反馈。即使它与同步字段以不同顺序到达,也不改变分数。网络入口可被调用,不能用装饰特效承担可信计分逻辑。
GameButton
Section titled “GameButton”using UdonSharp;using UnityEngine;
[UdonBehaviourSyncMode(BehaviourSyncMode.None)]public class GameButton : UdonSharpBehaviour{ public GameManager manager; public Light buttonLight; public int buttonIndex; private bool isGlowing;
public void SetGlowing(bool glowing) { isGlowing = glowing; if (buttonLight != null) buttonLight.intensity = glowing ? 4f : 0f; }
public override void Interact() { if (!isGlowing || manager == null) return; manager._RequestHit(buttonIndex); }}GameButton 只执行本地逻辑,因此使用 None。通过本地引用调用 Manager 不属于在 GameButton 上接收网络事件;网络事件由 Manager 发出并接收。
Inspector 配置:
| 字段 | 值 |
|---|---|
| Manager | 同一个 GameManager |
| Button Light | 当前按钮的 Light |
| Button Index | 四个按钮分别为 0、1、2、3 |
| Interaction Text | 按 / Press |
在 Manager 的 Buttons 数组按 0–3 顺序填写四个 GameButton,不能留空项或重复对象。把计分板 TMP 组件拖入 Scoreboard Text。可选的 Reset Sound 需引用 AudioSource,填写短音效并取消 Play On Awake、Loop;为了比较两端反馈可先用低音量 2D 音频。未配置这个引用不会影响清分。
ResetButton
Section titled “ResetButton”using UdonSharp;using UnityEngine;
[UdonBehaviourSyncMode(BehaviourSyncMode.None)]public class ResetButton : UdonSharpBehaviour{ public GameManager manager;
public override void Interact() { if (manager != null) manager._RequestReset(); }}挂到有 Collider 的 ResetButton 上,填 Manager,提示设为 重置分数 / Reset scores。本例允许任何有效实例玩家重置,包括没有计分槽位的观战者;Owner 仍验证真实调用者,再清分和增加 roundId。若采用仅主持人可重置的另一套规则,需明确告知并在 Owner 的 ResetGame 中增加身份条件,而不只是隐藏按钮。
可选的本地 0.1 秒输入防抖
Section titled “可选的本地 0.1 秒输入防抖”Manager 的 Use Local Debounce 默认不勾。勾选后,_RequestHit 在一次允许提交后,将本机下一次可提交时间设为 Time.time + 0.1f,期间再次进入便返回。它也会拦截短间隔跨回合输入,只减少本机重复提交,不是网络互斥、请求确认或反作弊。
SubmitHit 的真实调用者、索引和 roundId 校验仍保留。另一台客户端有自己的计时器,可能同时提交;Owner 仍按实际收到的有效请求裁决。NetworkCallable 的发送限速也不等于这个本地防抖。
在测试副本里,在 _RequestHit 的防抖检查之前和 SendCustomNetworkEvent 之前分别加一条带 Time.time 的 [GameInput] 日志。临时从一个 Interact 连续调用两次 manager._RequestHit(buttonIndex):不勾时看到两次提交日志,勾选时只看到一次;间隔超过 0.1 秒且当前按钮仍有效时可再次提交。然后恢复单次调用,做两客户端同时按同一回合的测试。前者验证本地输入门槛,后者验证 Owner 回合裁决,不能相互替代。
单客户端测试
Section titled “单客户端测试”- 等初始化完成,确认一个按钮发光,计分板出现本机玩家。
- 按未发光按钮,确认分数不变。
- 按发光按钮,确认加一分并切换到不同按钮。
- 连续按旧按钮,确认不会给旧回合重复计分。
- 点击重置,确认分数清零、当前按钮有效;音效为空时仍能工作。
若计分板不显示,分别检查 Console、TMP 字体、Manager 引用、Buttons 数组与 ready 状态。不把所有问题归为「OnPlayerJoined 没跑」。
多客户端测试
Section titled “多客户端测试”| 场景 | 预期 |
|---|---|
| Alpha 按有效按钮 | Owner 接受后,双方看到 Alpha 加一分 |
| 两人同时按同一回合 | 只接受一个有效请求,其他请求因回合变化被忽略 |
| Charlie 中途加入 | 收到当前按钮和已有分数,容量允许时出现自己的槽位 |
| 玩家离开 | 其槽位清除,剩余玩家分数保留 |
| 当前 Owner 离开 | 新 Owner 核对名单,仍能接受请求 |
| 重置前的请求延迟到达 | observedRound 不匹配,不改变新回合分数 |
| 无计分槽位的玩家按重置 | Owner 验证调用者有效后清分并开始新回合 |
满员测试不必召集 17 人:在独立测试副本将 MAX_PLAYERS 临时改为 1,创建新实例,让第二位玩家确认自己不占槽位,再按重置,核对第一位玩家清分;测试后恢复 16 并重新构建。
检验请求顺序时记录发送者 ID、buttonIndex、observedRound 和 Owner 当前 roundId。不要仅根据两边画面中的点击动画断定请求先后。
Owner 离线前未成功同步的变化可能丢失;转移期间发给旧 Owner 的请求也可能需要玩家再次操作。本例没有实现跨断线的事务确认或反作弊,不适合承诺竞赛级公平与永久积分。
名单未更新时的检查链
Section titled “名单未更新时的检查链”- 在
OnPlayerJoined、OnPlayerLeft和_InitializeOwner入口记录本机 ID、Owner、ready 与玩家 ID,确认哪台机器有权写数组。 - 在
ReconcilePlayers中记录查重和空槽结果,区分玩家尚未可解析、容量满和已经注册;核对playerIds[i]与scores[i]是同一下标。 - 确认 Owner 修改后执行
PublishState,并加入下面的回调检查发送尝试。success=true不等于每个接收端已经显示了结果。
public override void OnPostSerialization(VRC.Udon.Common.SerializationResult result){ Debug.Log($"[GameSync] success={result.success}, bytes={result.byteCount}, " + $"clogged={Networking.IsClogged}");}- 在另一端
OnDeserialization入口记录收到的槽位,再确认UpdateUI、TMP 引用和字体。数组正确而姓名暂未解析,与数组未收到是两种问题。Unity / ClientSim 看 Console,实际客户端看各自客户端日志。
可选扩展:难度按钮与超时换灯
Section titled “可选扩展:难度按钮与超时换灯”下面的改动基于完整 GameManager;先在副本中完成,不和主例的无计时规则混测。示例将三档回合时限设为 5、3、1.5 秒,数值只供对照。
- 在 GameManager 的同步字段区域增加:
[UdonSynced] private int difficulty;[UdonSynced] private double roundEndsAt;- 在
ActivateRandomButton()方法开头、检查 Buttons 数组之前加入下面两行。这样初始回合、正确点击、重置和难度修改都会安排新时限;Owner 接管已有有效回合时不重新调用它,保留同步截止时间。
float seconds = difficulty == 0 ? 5f : (difficulty == 1 ? 3f : 1.5f);roundEndsAt = Networking.GetServerTimeInSeconds() + seconds;- 在 GameManager 类内加入以下方法。超时只由 Owner 裁决,每次换灯都增加 roundId;难度请求也带上请求端所见回合,避免旧请求改写新回合。
public void _RequestDifficulty(int level){ if (!ready) return; SendCustomNetworkEvent(NetworkEventTarget.Owner, nameof(SetDifficulty), level, roundId);}
[NetworkCallable]public void SetDifficulty(int level, int observedRound){ if (!Networking.IsOwner(gameObject) || !ready) return; if (!Utilities.IsValid(NetworkCalling.CallingPlayer)) return; if (level < 0 || level > 2 || observedRound != roundId) return; difficulty = level; roundId++; ActivateRandomButton(); PublishState();}
private void Update(){ if (!Networking.IsOwner(gameObject) || !ready || activeButtonIndex < 0) return; if (Networking.GetServerTimeInSeconds() < roundEndsAt) return; roundId++; ActivateRandomButton(); PublishState();}同时在 SubmitHit 的 Owner/ready 检查之后增加 if (Networking.GetServerTimeInSeconds() >= roundEndsAt) return;,使已过截止时间、但 Update 尚未换灯的请求也不能得分。这里只按 Owner 收到请求时的服务器时间估计判断,不推断现实中玩家按下的时刻。
- 建立三个带普通 Collider 的 Cube,分别挂以下脚本。Manager 引用同一对象,Level 分别填 0、1、2,并在旁边标明对应时限。按钮不接管 Manager。
using UdonSharp;using UnityEngine;
[UdonBehaviourSyncMode(BehaviourSyncMode.None)]public class DifficultyButton : UdonSharpBehaviour{ public GameManager manager; public int level;
public override void Interact() { if (manager != null) manager._RequestDifficulty(level); }}- 在
UpdateUI原来的计分板字符串初始化行中加上difficulty,例如string text = $"计分板 / 难度 {difficulty}\n\n";。两人确认相同难度,停止点击并观察超时换灯;在截止前后分别点击,检查过期请求不加分。让第三人中途加入、再让 Owner 离开,核对难度、分数和回合仍可继续。
这个扩展允许所有有效实例玩家改难度。若玩法需要主持人或准备阶段限制,要在 Owner 的 SetDifficulty 中补相应条件;隐藏按钮不改变接收端的规则。
- 给重置添加本地粒子和音效,检查状态与效果的不同到达顺序
- 保存同步的游戏开始时间,各客户端按服务器时间估计倒计时,由 Owner 决定结束状态
- 增加可调回合时长,Owner 在超时后增加 roundId 并切换按钮,使过期点击失效
- SDK 支持代码中的 NetworkCallable 和参数事件
- 所有按钮引用、索引和 UI 引用完整
- 仅 Owner 写共享状态,客户端不反复接管计分对象
- 请求者身份、按钮范围和回合编号均校验
- 初始同步、后加入、满员、离开和接管均测试
- Owner 本地 UI 与远端 UI 一致
- 未把网络到达顺序描述成现实动作的绝对先后