Unity Multiplayer

Unity Multiplayer — Netcode for GameObjects (NGO)

此技能的作用

指导使用 Netcode for GameObjects（NGO）进行多人游戏开发。 涵盖网络设置、创建 NetworkBehaviours、通过 NetworkVariables 同步 状态、使用 RPCs（ServerRpc / ClientRpc）进行通信，以及集成 Unity Gaming Services（Lobby + Relay）。

范围：仅限 NGO。不包括 DOTS Netcode、Mirror 或 Photon。

前提条件

• 软件包 com.unity.netcode.gameobjects (>= 1.5.0)
• 场景中有一个 NetworkManager GameObject
• 使用 Unity Transport（com.unity.transport）作为传输层
• （可选）Unity Gaming Services 账号，用于 Lobby / Relay

快速开始

1. 安装软件包 — Window > Package Manager > Netcode for GameObjects
2. 添加 NetworkManager — 创建空 GameObject，并添加 NetworkManager 组件
3. 配置传输层 — 在同一个 GameObject 上添加 UnityTransport，并在 NetworkManager 中指定它
4. 创建玩家预制件 — 创建包含 NetworkObject 和你的 NetworkBehaviour 的预制件
5. 在 NetworkManager > Player Prefab 中指定预制件
6. 以 Host 模式测试 — NetworkManager.Singleton.StartHost()

决策树

Architecture reseau...
+-- Prototype / local coop ?
|   +-- -> Host mode (client + server sur meme machine)
+-- Jeu en ligne casual (2-8 joueurs) ?
|   +-- -> Host mode + Unity Relay (pas besoin de serveur dedie)
+-- Jeu competitif / anti-cheat important ?
|   +-- -> Dedicated server (autoritative)
+-- Besoin de matchmaking ?
    +-- -> Unity Lobby + Relay

补充软件包（Unity 6+）

Multiplayer Center（Window > Multiplayer Center）

Unity 推荐用于配置多人游戏项目的入口：

• 根据游戏类型（休闲、竞技、MMO）推荐要安装的软件包
• 自动配置 NetworkManager 和传输层
• 提供预先配置好的多人游戏项目模板
• 指引使用合适的 Gaming Services（Lobby、Relay、Matchmaker）

从零开始新项目时，建议使用 Multiplayer Center，而不是手动配置。

Dedicated Server 软件包（com.unity.dedicated-server）

适用于使用专用服务器（而非 Host 模式）的游戏：

• Multiplayer Roles：在 Build Profiles 中将内容标记为 Client、Server 或 ClientAndServer
• Content Selection：构建流水线会自动剥离与角色无关的资源（服务器端的纹理、音频、UI）
• 影响：服务器构建体积可减少 50-80%
• 设置：安装软件包 → 在 Build Profiles 中配置角色 → 为组件/GameObject 指定角色

仅适用于会发布独立服务器二进制文件的游戏。Host 模式下不需要。

分步指南

第 1 步 — 设置 NetworkManager

// Demarrer une session:
NetworkManager.Singleton.StartHost();   // host mode
NetworkManager.Singleton.StartServer(); // dedicated
NetworkManager.Singleton.StartClient(); // client

第 2 步 — 创建 NetworkBehaviour

using Unity.Netcode;
using UnityEngine;

public class PlayerController : NetworkBehaviour
{
    [SerializeField] private float speed = 5f;

    // NetworkVariable — synchronise automatiquement server -> clients
    private NetworkVariable<int> score = new(0,
        NetworkVariableReadPermission.Everyone,
        NetworkVariableWritePermission.Server);

    public override void OnNetworkSpawn()
    {
        if (IsOwner)
        {
            // Setup specifique au joueur local
        }
        score.OnValueChanged += OnScoreChanged;
    }

    public override void OnNetworkDespawn()
    {
        score.OnValueChanged -= OnScoreChanged;
    }

    private void Update()
    {
        if (!IsOwner) return; // Seul le owner controle son personnage

        var input = new Vector3(Input.GetAxis("Horizontal"), 0, Input.GetAxis("Vertical"));
        transform.position += input * (speed * Time.deltaTime);
    }

    // Server RPC — appele par le client, execute sur le server
    [ServerRpc]
    public void AddScoreServerRpc(int points)
    {
        score.Value += points;
    }

    private void OnScoreChanged(int oldValue, int newValue)
    {
        Debug.Log($"Score: {oldValue} -> {newValue}");
    }
}

第 3 步 — 设置 Lobby + Relay（可选，适用于在线游戏）

Lobby + Relay 完整代码见 references/netcode-patterns.md。

工作流：

1. UnityServices.InitializeAsync() + SignInAnonymouslyAsync()
2. Host：RelayService.Instance.CreateAllocationAsync() → 获取加入码 → StartHost()
3. 客户端：RelayService.Instance.JoinAllocationAsync(joinCode) → StartClient()

严格规则

始终：

• 处理玩家输入前，检查 IsOwner
• 修改权威状态前，检查 IsServer
• 使用 NetworkVariable 保存同步状态（不要使用普通字段）
• 为 RPC 方法添加后缀：ServerRpc 和 ClientRpc
• 实现 OnNetworkSpawn / OnNetworkDespawn（网络逻辑不要放在 Start/OnDestroy 中）
• 在 OnNetworkDespawn 中取消订阅 OnValueChanged 回调

绝不：

• 在多人游戏中直接使用 Instantiate — 使用 NetworkObject.Spawn()（仅限服务器）
• 让客户端逻辑直接修改服务器状态
• 使用 NetworkVariable<string> 或未自定义序列化的引用类型
• 无故在非所有者对象上执行开销大的 Update()

优先使用：

• NetworkVariable 保存持续状态（位置、生命值、分数）
• ServerRpc 执行一次性操作（射击、购买、交互）
• ClientRpc 提供视觉/音频反馈（爆炸、声音）

相关技能

• /unity-code-gen — 生成 NetworkBehaviour 类型
• /unity-build-config — dedicated server 的构建配置
• /unity-test — 使用多个实例进行并行测试
• 网络故障难以追踪？使用 /unity-debug（Unity Debug）

故障排除

问题	解决方案
"NetworkObject is not spawned"	检查 prefab 是否包含 NetworkObject 组件，以及是否通过 NetworkManager 生成
ServerRpc 未调用	检查方法名称是否包含后缀 ServerRpc，并确认调用者是 owner（或设置 RequireOwnership = false）
状态不同步	使用 NetworkVariable 代替本地变量。检查读写权限
延迟明显	实现客户端预测（参见 references/netcode-advanced.md）
"Object already spawned"	不要对已生成的对象调用 Spawn()。检查生成流程
客户端无法连接	检查 UnityTransport 中的地址/端口。使用 Relay 时，检查 join code
NetworkVariable 未更新	只有 server（或根据 WritePermission 确定的 owner）可以写入。检查权限