跳转到内容

30. 做一个多人小游戏

约 90 分钟 内容:进阶 动手章

场上有四个按钮,每回合只有一个发光。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 + TextMeshProUGUI

Manager 保存同步数据,按钮只提交本机请求。点击不会反复接管 Manager 所有权,避免多个客户端各自基于旧分数写回。

  • activeButtonIndex:当前发光按钮
  • roundId:当前回合编号,拒绝延迟到达的旧请求
  • playerIds / scores:并行数组,同一下标代表同一玩家
  • Owner:处理有效请求并发布状态
  • 其他客户端:接收状态并更新按钮与计分板

代码使用 SDK 3.8.1+ 的 NetworkCallable 与带参数网络事件,运行前确认项目 SDK 支持这些 API。

将四个 Cube 放在可操作高度,保留普通 Box Collider,不勾 Is Trigger:

Button_0 Position -2, 1, 0 Scale 0.5, 0.3, 0.5
Button_1 Position -0.7, 1, 0 Scale 0.5, 0.3, 0.5
Button_2 Position 0.7, 1, 0 Scale 0.5, 0.3, 0.5
Button_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.cs
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;
}
}
  • 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.cs
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.cs
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 中增加身份条件,而不只是隐藏按钮。

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 回合裁决,不能相互替代。

  1. 等初始化完成,确认一个按钮发光,计分板出现本机玩家。
  2. 按未发光按钮,确认分数不变。
  3. 按发光按钮,确认加一分并切换到不同按钮。
  4. 连续按旧按钮,确认不会给旧回合重复计分。
  5. 点击重置,确认分数清零、当前按钮有效;音效为空时仍能工作。

若计分板不显示,分别检查 Console、TMP 字体、Manager 引用、Buttons 数组与 ready 状态。不把所有问题归为「OnPlayerJoined 没跑」。

场景预期
Alpha 按有效按钮Owner 接受后,双方看到 Alpha 加一分
两人同时按同一回合只接受一个有效请求,其他请求因回合变化被忽略
Charlie 中途加入收到当前按钮和已有分数,容量允许时出现自己的槽位
玩家离开其槽位清除,剩余玩家分数保留
当前 Owner 离开新 Owner 核对名单,仍能接受请求
重置前的请求延迟到达observedRound 不匹配,不改变新回合分数
无计分槽位的玩家按重置Owner 验证调用者有效后清分并开始新回合

满员测试不必召集 17 人:在独立测试副本将 MAX_PLAYERS 临时改为 1,创建新实例,让第二位玩家确认自己不占槽位,再按重置,核对第一位玩家清分;测试后恢复 16 并重新构建。

检验请求顺序时记录发送者 ID、buttonIndex、observedRound 和 Owner 当前 roundId。不要仅根据两边画面中的点击动画断定请求先后。

Owner 离线前未成功同步的变化可能丢失;转移期间发给旧 Owner 的请求也可能需要玩家再次操作。本例没有实现跨断线的事务确认或反作弊,不适合承诺竞赛级公平与永久积分。

  1. 在 OnPlayerJoined、OnPlayerLeft 和 _InitializeOwner 入口记录本机 ID、Owner、ready 与玩家 ID,确认哪台机器有权写数组。
  2. 在 ReconcilePlayers 中记录查重和空槽结果,区分玩家尚未可解析、容量满和已经注册;核对 playerIds[i] 与 scores[i] 是同一下标。
  3. 确认 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}");
}
  1. 在另一端 OnDeserialization 入口记录收到的槽位,再确认 UpdateUI、TMP 引用和字体。数组正确而姓名暂未解析,与数组未收到是两种问题。Unity / ClientSim 看 Console,实际客户端看各自客户端日志。

可选扩展:难度按钮与超时换灯

Section titled “可选扩展:难度按钮与超时换灯”

下面的改动基于完整 GameManager;先在副本中完成,不和主例的无计时规则混测。示例将三档回合时限设为 5、3、1.5 秒,数值只供对照。

  1. 在 GameManager 的同步字段区域增加:
[UdonSynced] private int difficulty;
[UdonSynced] private double roundEndsAt;
  1. 在 ActivateRandomButton() 方法开头、检查 Buttons 数组之前加入下面两行。这样初始回合、正确点击、重置和难度修改都会安排新时限;Owner 接管已有有效回合时不重新调用它,保留同步截止时间。
float seconds = difficulty == 0 ? 5f : (difficulty == 1 ? 3f : 1.5f);
roundEndsAt = Networking.GetServerTimeInSeconds() + seconds;
  1. 在 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 收到请求时的服务器时间估计判断,不推断现实中玩家按下的时刻。

  1. 建立三个带普通 Collider 的 Cube,分别挂以下脚本。Manager 引用同一对象,Level 分别填 0、1、2,并在旁边标明对应时限。按钮不接管 Manager。
DifficultyButton.cs
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);
}
}
  1. 在 UpdateUI 原来的计分板字符串初始化行中加上 difficulty,例如 string text = $"计分板 / 难度 {difficulty}\n\n";。两人确认相同难度,停止点击并观察超时换灯;在截止前后分别点击,检查过期请求不加分。让第三人中途加入、再让 Owner 离开,核对难度、分数和回合仍可继续。

这个扩展允许所有有效实例玩家改难度。若玩法需要主持人或准备阶段限制,要在 Owner 的 SetDifficulty 中补相应条件;隐藏按钮不改变接收端的规则。

  • 给重置添加本地粒子和音效,检查状态与效果的不同到达顺序
  • 保存同步的游戏开始时间,各客户端按服务器时间估计倒计时,由 Owner 决定结束状态
  • 增加可调回合时长,Owner 在超时后增加 roundId 并切换按钮,使过期点击失效
  • SDK 支持代码中的 NetworkCallable 和参数事件
  • 所有按钮引用、索引和 UI 引用完整
  • 仅 Owner 写共享状态,客户端不反复接管计分对象
  • 请求者身份、按钮范围和回合编号均校验
  • 初始同步、后加入、满员、离开和接管均测试
  • Owner 本地 UI 与远端 UI 一致
  • 未把网络到达顺序描述成现实动作的绝对先后