unity-networking

Unity 网络与多人游戏

概述

Unity 多人游戏系统和后端服务实现参考。涵盖主要网络框架、权限模型、常见多人游戏模式，以及 Unity Gaming Services 集成。

网络框架对比

框架	类型	适用场景	许可证
Netcode for GameObjects (NGO)	客户端托管 / 专用	Unity 原生项目、UGS 集成	免费（Unity）
Mirror	客户端托管 / 专用	开源替代方案、成熟的生态系统	MIT
Photon PUN 2	云托管	快速原型开发、基于房间的游戏	免费层级 + 付费
Photon Fusion 2	云托管 / 可自托管	竞技游戏、基于 Tick 的模拟	免费层级 + 付费
Fish-Net	客户端托管 / 专用	对性能要求高的场景、Mirror 替代方案	MIT

Netcode for GameObjects (NGO)

设置

1. 通过 Package Manager 安装：com.unity.netcode.gameobjects
2. 将 NetworkManager 添加到场景中的 GameObject
3. 选择传输方式（默认使用 Unity Transport）
4. 为网络化预制件添加 NetworkObject 组件
5. 在 NetworkManager 的预制件列表中注册预制件

核心组件

组件	用途
NetworkManager	管理连接、生成和场景管理
NetworkObject	所有网络化 GameObject 都必须添加此组件
NetworkBehaviour	网络化脚本的基类（替代 MonoBehaviour）
NetworkVariable<T>	带所有权 / 权限控制的同步变量
NetworkTransform	自动同步位置 / 旋转
NetworkAnimator	自动同步 Animator 参数

RPC（远程过程调用）

public class PlayerCombat : NetworkBehaviour
{
    NetworkVariable<int> _health = new(100,
        NetworkVariableReadPermission.Everyone,
        NetworkVariableWritePermission.Server);

    [ServerRpc]
    void AttackServerRpc(ulong targetId)
    {
        // Runs on server - validate and apply damage
        if (!IsServer) return;
        var target = NetworkManager.SpawnManager.SpawnedObjects[targetId];
        target.GetComponent<PlayerCombat>().TakeDamage(10);
    }

    [ClientRpc]
    void PlayHitEffectClientRpc(Vector3 position)
    {
        // Runs on all clients - visual feedback only
        Instantiate(hitVFX, position, Quaternion.identity);
    }

    void TakeDamage(int amount)
    {
        _health.Value -= amount;
        PlayHitEffectClientRpc(transform.position);
    }
}

RPC 类型	方向	用途
[ServerRpc]	客户端 -> 服务端	玩家操作、请求
[ClientRpc]	服务端 -> 所有客户端	VFX、音效、UI 更新
[ClientRpc(SendTo.Owner)]	服务端 -> 所有者客户端	针对所有者的反馈

NetworkVariable 权限

// Server-writable (default) - authoritative state
NetworkVariable<int> score = new(0, writePerm: NetworkVariableWritePermission.Server);

// Owner-writable - client-authoritative (use sparingly)
NetworkVariable<Vector3> cursorPos = new(writePerm: NetworkVariableWritePermission.Owner);

使用 OnValueChanged 回调来响应 UI 变化：

_health.OnValueChanged += (oldVal, newVal) => healthBar.value = newVal;

权限模型

模型	描述	适用场景
服务端权威	服务端验证所有操作，客户端保持轻量	竞技游戏、反作弊至关重要的场景
客户端权威	客户端拥有自身状态，服务端负责转发	合作游戏、基于信任的场景
客户端预测 + 服务端校正	客户端在本地进行预测，服务端负责校正	FPS、快节奏动作游戏
中继 / 监听服务器	一名玩家负责托管，其他玩家通过中继连接	休闲游戏、小型大厅

服务端权威流程

Client: Press "Attack" -> Send ServerRpc(targetId)
Server: Validate range/cooldown -> Apply damage -> Update NetworkVariable
Server: Send ClientRpc for VFX
All Clients: Play hit effect

永远不要信任客户端数据。在服务端验证位置、冷却时间、弹药和视线范围。

常见多人游戏模式

大厅系统

1. Player authenticates (UGS Auth / custom)
2. Player creates or joins lobby (UGS Lobby / custom)
3. Lobby fills -> host starts game
4. Relay allocation for NAT traversal (UGS Relay)
5. All players connect to relay
6. NetworkManager starts host/client

生成与销毁

// Server-side spawning
var instance = Instantiate(prefab, spawnPoint, Quaternion.identity);
instance.GetComponent<NetworkObject>().SpawnWithOwnership(clientId);

// Server-side despawning
networkObject.Despawn(); // Removes from all clients

场景管理

使用 NetworkManager.SceneManager.LoadScene("GameScene", LoadSceneMode.Single) 同步加载场景。只能由服务端 / 主机调用。

REST API 和 WebSocket 集成

REST API（UnityWebRequest）

async Awaitable<T> GetAsync<T>(string url)
{
    using var request = UnityWebRequest.Get(url);
    request.SetRequestHeader("Authorization", $"Bearer {token}");
    await request.SendWebRequest();
    if (request.result != UnityWebRequest.Result.Success)
        throw new Exception(request.error);
    return JsonUtility.FromJson<T>(request.downloadHandler.text);
}

简单类型使用 JsonUtility，复杂序列化使用 Newtonsoft.Json（com.unity.nuget.newtonsoft-json）。始终对 UnityWebRequest 使用 using，以防止内存泄漏。

WebSocket（NativeWebSocket / WebSocketSharp）

对于实时的非游戏通信（聊天、通知），请使用 WebSocket 库。NativeWebSocket 可跨平台运行，包括 WebGL。

Unity Gaming Services (UGS)

服务	包	用途
身份验证	com.unity.services.authentication	匿名登录／平台登录
Lobby	com.unity.services.lobby	房间创建、匹配
Relay	com.unity.services.relay	P2P 的 NAT 穿透
Cloud Save	com.unity.services.cloudsave	服务端玩家数据
Leaderboards	com.unity.services.leaderboards	排名计分板
Economy	com.unity.services.economy	虚拟货币、购买
Analytics	com.unity.services.analytics	玩家行为追踪
Matchmaker	com.unity.services.matchmaker	基于技能的匹配

使用任何服务前，请先初始化 UGS：

await UnityServices.InitializeAsync();
await AuthenticationService.Instance.SignInAnonymouslyAsync();

Firebase 和 PlayFab

对于需要 Realtime Database、Cloud Functions 和 FCM 推送通知的独立／移动项目，请使用 Firebase。对于需要玩家分群、A/B 测试和自动化规则处理的 LiveOps 重度游戏，请使用 PlayFab。两者都通过各自的下载页面提供 Unity SDK。

更多资源

参考文件

• references/netcode-advanced.md -- 客户端预测与校正的实现、兴趣管理、网络 LOD、带宽优化、自定义序列化、传输层配置
• references/backend-services.md -- UGS 详细设置指南、Firebase／PlayFab 集成模式、REST API 架构、身份验证流程、排行榜与经济系统实现