Unity Multiplayer

Unity Multiplayer — Netcode for GameObjects (NGO)

このスキルでできること

Netcode for GameObjects（NGO）を使ったマルチプレイヤー開発をガイドします。 ネットワークのセットアップ、NetworkBehaviour の作成、NetworkVariables による状態の同期、 RPC（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）を使用すること
• （任意）Lobby / Relay 用の Unity Gaming Services アカウント

クイックスタート

1. パッケージをインストールする — Window > Package Manager > Netcode for GameObjects
2. NetworkManager を追加する — 空の GameObject に NetworkManager コンポーネントを追加します
3. トランスポートを設定する — 同じ GameObject に UnityTransport を追加し、NetworkManager に割り当てます
4. プレイヤー用プレハブを作成する — NetworkObject + 独自の NetworkBehaviour を含むプレハブを作成します
5. プレハブを割り当てる — NetworkManager > Player Prefab
6. ホストモードでテストする — 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）

専用サーバーを使うゲーム（ホストモードではない場合）向けです。

• Multiplayer Roles：Build Profiles でコンテンツに Client、Server、または ClientAndServer の役割を指定します
• Content Selection：ビルドパイプラインが、その役割に関係のないアセット（サーバー用のテクスチャ、オーディオ、UI など）を自動的に除外します
• 効果：サーバービルドのサイズを 50～80% 削減できます
• セットアップ：パッケージをインストール → Build Profiles で役割を設定 → コンポーネント / GameObject に役割を割り当てます

サーバー用バイナリを別途出荷するゲームでのみ使用します。ホストモードでは不要です。

ステップバイステップガイド

Step 1 — NetworkManager のセットアップ

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

Step 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}");
    }
}

Step 3 — Lobby + Relay のセットアップ（任意、オンラインゲーム向け）

Lobby + Relay のコード一式は references/netcode-patterns.md にあります。

ワークフロー：

1. UnityServices.InitializeAsync() + SignInAnonymouslyAsync()
2. ホスト：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 — 専用サーバー向けのビルドを設定する
• /unity-test — 複数のインスタンスを並列でテストする
• ネットワークの問題の追跡が難しい場合は、/unity-debug（Unity Debug）を使用します

トラブルシューティング

問題	解決策
"NetworkObject is not spawned"	プレハブに NetworkObject コンポーネントがあり、NetworkManager 経由でスポーンされていることを確認します
ServerRpc が呼び出されない	メソッド名に ServerRpc のサフィックスが付いていること、および呼び出し元がオーナーであること（または RequireOwnership = false であること）を確認します
状態の不一致	ローカル変数ではなく NetworkVariable を使用します。読み取り／書き込み権限を確認します
目に見える遅延	クライアント側予測を実装します（references/netcode-advanced.md を参照）
"Object already spawned"	すでにスポーンされているオブジェクトに対して Spawn() を呼び出さないでください。スポーンのフローを確認します
クライアントが接続されない	UnityTransport のアドレス／ポートを確認します。Relay を使用している場合は、参加コードを確認します
NetworkVariable が更新されない	書き込みできるのはサーバーのみです（または WritePermission に応じてオーナー）。権限を確認します