godot-adapt-single-to-multiplayer

絶対にしてはいけないこと（マルチプレイヤーのエキスパート向けルール）

セキュリティと権限

• クライアントから報告された状態を絶対に信用しないでください — クライアントが管理するのは「入力」であり、「位置」や「体力」ではありません。サーバーはすべての座標と体力の変更を検証する必要があります。
• 権限チェックに get_tree() グループを絶対に使わないでください — is_multiplayer_authority() を使ってください。高遅延環境での参加時、グループ登録は非決定的です。
• RPC の呼び出し頻度に制限を設けない状態を絶対に許容しないでください — 悪意のあるクライアントは、1 秒間に 10,000 回 FireWeapon RPC を呼び出す可能性があります。必ずレート制限（net_rpc_rate_limiter.gd）を実装してください。

移動とラグ

• クライアントサイド予測を絶対に省略しないでください — 予測なしの移動は「重く」、反応が鈍く感じられます。ローカルで移動を予測し、サーバーとの不一致がある場合にのみ修正してください。
• ピアを 60Hz で同期しないでください — フレームごとに状態全体を送信すると、クライアントの帯域幅が飽和します。低いティックレート（20～30Hz）を使い、パケット間を補間してください。
• ピアの位置を絶対に瞬間移動させないでください — 位置が急に更新されると「ジッター」が発生します。過去の状態をバッファに保存し、100ms の遅延を設けてその間を線形補間してください。

帯域幅と同期

• 可能な限り「完全な浮動小数点数」を同期しないでください — Vector3 データを量子化（小数点以下を切り捨て）すると、帯域幅を 50％以上節約できます。デルタ同期を有効にした MultiplayerSynchronizer を使ってください。
• 「途中参加者」を絶対に無視しないでください — ゲーム途中に参加したプレイヤーには、既存の環境変化が見えません。ピアの接続時に、ワールド状態の完全な「スナップショット」をブロードキャストしてください。
• ping が 0ms の環境だけで絶対にテストしないでください — localhost ではすべてが正常に動作します。シミュレーター（net_latency_simulator.gd）で ping を 150ms に設定し、同期のバグを見つけてください。

---

利用可能なスクリプト

必須：まずアーキテクチャの決定ツリーを確認し、その後にゴールデンパスのスクリプトを確認してください。詳細なレイテンシーワークフロー → references/latency-testing.md。

権限／トランスポートブリッジ

multiplayer_sync.gd

リモートピア向けに MultiplayerSynchronizer の補間を追加する場合は必須です。条件：権限を持つ側がトランスフォームを管理し、権限を持たない側が補間します。

rpc_bridge.gd

シグナルから RPC へのブリッジとして必須です。条件：ゲームプレイでローカルシグナルを発行し、ブリッジが権限を検証して RPC を各所に送信します。

予測／ラグ／ロビー

net_prediction_reconciliation.gd

サーバーの調整に向けた、CharacterBody の予測と入力バッファーの再生。

net_snapshot_interpolation.gd

リモートピア向けのスナップショット補間／ジッターバッファー。

net_auth_server_validator.gd

権威サーバーによる検証（位置、速度、アクション）。

net_rpc_rate_limiter.gd

RPC の大量呼び出し／マクロ対策。

net_interest_management.gd

距離ベースの可視性制御による帯域幅の削減。

net_delta_compression_sync.gd

デルタ同期向けの量子化と重要度チェック。

net_lag_compensation.gd

ヒット判定のためのサーバー側巻き戻し。

net_lobby_late_join_sync.gd

途中参加者向けのワールドスナップショットの初期同期。

診断

net_latency_simulator.gd

リリース前に必須 — references/latency-testing.md を参照してください。

net_debug_overlay_monitor.gd

RTT／損失／ジッターのオーバーレイ。

net_upnp_discovery_logic.gd

リッスンサーバー／P2P ホスト向けの UPNP ポートマッピング。

---

アーキテクチャパターン

パターン	用途	スクリプトのゴールデンパス
権威サーバー	PvP、経済システム、不正行為のリスク	rpc_bridge.gd → net_auth_server_validator.gd → 予測／調整
P2P ロックステップ	2～4 人の協力プレイ、不正行為のリスクが低い	決定論的な入力 + net_upnp_discovery_logic.gd
ハイブリッド／ホスト権限	4～8 人のパーティーゲーム	ホスト権限 + 途中参加者向けスナップショット

---

移行の基本手順（ホスト／参加のチュートリアルをインラインに含めない）

1. 入力（クライアント）とシミュレーション（権限）を分離します。
2. プレイヤーノードごとに multiplayer_authority を設定し、クライアントはインテントのみを送信します。
3. プロパティのレプリケーション／リモート補間には、multiplayer_sync.gd が必須です。
4. ワイヤーを介してやり取りするゲームプレイイベントには、rpc_bridge.gd が必須です。
5. 予測／ラグ補償スクリプトは、必要とするジャンルにのみ追加します。
6. latency-testing のリファレンスと net_latency_simulator.gd を使い、約 150 ms の RTT で検証します。

エキスパートの知見（理由 — 本文に残す）

• クライアント予測 — 理由：ローカルシミュレーションがないと、体感入力ラグは RTT の 2 倍になります。サーバーの補正後にバッファー済みの入力を再生します（net_prediction_reconciliation.gd）。
• 補間バッファー — 理由：未加工の同期パケットはジッターが発生します。約 100 ms の遅延を設け、スナップショット間を線形補間します（net_snapshot_interpolation.gd）。
• ヒット巻き戻し — 理由：クライアントは過去のワールド状態に向けて射撃します。サーバーはレイキャストの前に PhysicsServer3D を使って RID を巻き戻します（net_lag_compensation.gd）。
• 入力送信レート — 理由：60 Hz の入力 RPC はアップリンクを圧迫します。重要度チェックを行いながら、20～30 Hz でまとめて送信します（net_delta_compression_sync.gd）。

判断ツリー：どのアーキテクチャを選ぶか？

要素	権威サーバー	P2P ロックステップ
プレイヤー数	8～100 以上	2～4
チート対策	重要	重要ではない
サーバーホスティング	利用可能	利用不可
ゲームプレイの種類	PvP、対戦型	協力プレイ、カジュアル
ラグ許容度	中（予測が有効）	低（同期ずれが発生）
開発の複雑さ	高	中

高度なネットワークのトピック

ピアツーピアの NAT トラバーサル（ホールパンチング）

P2P アーキテクチャでは、クライアントがファイアウォールの内側にあることがよくあります。UPNP（Universal Plug and Play）は最初の防御策です。net_upnp_discovery_logic.gd を使って、ゲームからルーターにポートフォワーディングを自動的に要求できます。

UPNP が機能しない場合：

• STUN/TURN：STUN サーバーを使って、パブリック IP とポートの組み合わせを検出します。
• リレーサーバー：直接接続できない場合は、リレーサーバー（TURN）にフォールバックし、2 つのピア間を中継します。

ネットワークのプロファイリングと可視化

ジッターのデバッグには、パケットのタイムラインを可視化することが重要です。次の項目をグラフ化するオーバーレイを提案します。

• パケット到着：物理フレームに対するパケットの到着時刻を示すスクロール式タイムライン。
• バッファーの健全性：補間ジッターバッファーのサイズを可視化します。
• RTT（往復時間）：遅延の急増をリアルタイムで示すグラフ。

詳細レシピ（必要に応じて）

トピック	リファレンス／スクリプト
予測／リコンシリエーション／補間	prediction-and-reconciliation.md
権限／チート対策／帯域幅	authority-and-security.md

リファレンス

段階的な開示：特定の API を調査する場合にのみ、公式ドキュメントへのリンクを開いてください。 作業を関連分野のピアに引き継ぐ場合にのみ、関連スキルを読み込んでください。ラティス全体を事前に読み込まないでください。

公式ドキュメント

• ハイレベルマルチプレイヤー — ゲームプレイの状態をシングルプレイヤーの経路から外へ送信する前に導入が必要な、RPC モード、権限、ピアのライフサイクルについて説明します。
• ネットワーキング — ホスト／参加の選択をプラットフォームや NAT の制約に合わせるための、トランスポートの概要（ENet／WebSocket／WebRTC）です。
• MultiplayerSynchronizer — 場当たり的な位置 RPC に代わる、プロパティのレプリケーション、差分同期、可視性フィルターについて説明します。
• MultiplayerSpawner — 後から参加するクライアントにもホストと同じシーンツリーが必要な場合の、スポーン／デスポーンのレプリケーションについて説明します。
• SceneMultiplayer — デフォルトの MultiplayerAPI 実装です。SceneTree 配下のルートパス、認証コールバック、RPC ルーティングについて説明します。
• ENetMultiplayerPeer — シングルプレイヤーゲームの LAN 対応や専用サーバー対応で広く使われる、UDP のホスト／クライアント用ピアです。
• MultiplayerAPI — multiplayer シングルトンのインターフェースです。ピア ID、シグナル、rpc／rpc_id の呼び出し口を提供します。
• MultiplayerPeer — すべての具体的なピアバックエンドで共通の、転送モードと接続状態について説明します。
• UPNP — 家庭用ルーターの内側にあるリッスンサーバー／P2P ホスト向けの、自動ポートマッピングについて説明します。
• WebRTC — ENet UDP だけではファイアウォールを通過できない場合に使える、ブラウザーに適した P2P 経路です。
• Node — 入力と状態の所有権を定める、set_multiplayer_authority／is_multiplayer_authority のルールについて説明します。
• PhysicsServer3D — SceneTree に副作用を与えずにサーバー側でヒット判定を巻き戻すための、RID の直接変換について説明します。

関連スキル

前提条件

• godot-input-handling — クライアントが意図を送信し、権限を持つ側が結果を管理できるよう、InputMap の読み取りとシミュレーションを分離します。
• godot-signal-architecture — ゲームプレイをトランスポートに結合せずに rpc_bridge.gd でラップできる、ローカルのシグナルグラフについて説明します。
• godot-autoload-architecture — ホスト／参加のフロー中にシーンが切り替わっても存続する、セッション／ロビー用 Autoload について説明します。

補完

• godot-multiplayer-networking — シングルプレイヤーからオンラインへの移行方針が固まった後に、RPC、ロビー、ENet のチューニングを幅広く扱います。
• godot-characterbody-2d — クライアント予測と再調整バッファーで再利用される、決定論的な move_and_slide の手順です。
• godot-physics-3d — ラグ補償の巻き戻しやヒット検証で照会する、ボディとシェイプの設定です。
• godot-raycasting-queries — 状態の巻き戻し後に、権威サーバー側でショットを判定するためのレイ／シェイプクエリです。
• godot-debugging-profiling — ローカルホストでは決して表面化しない同期バグを見つける、RTT／ジッターのオーバーレイとリモートデバッグの習慣です。
• godot-export-builds — 実際の複数インスタンステスト向けの、ヘッドレス／専用サーバーのエクスポートプリセットと CLI フラグです。
• godot-server-architecture — 巻き戻しや専用ピアで使用する、PhysicsServer／RID のパターンとヘッドレスホストの基盤です。

下流／利用側

• godot-genre-shooter-fps — このスキルの予測とラグ補償に依存する、ヒットスキャン／飛翔体の操作感です。
• godot-genre-battle-royale — BR 規模における、多数のピア向けの関心管理と途中参加時のスナップショットです。
• godot-monte-carlo-balancer — ネットコードの変更によって実質的な武器のタイミングが変わった後に、経済バランス／TTK を再調整します。
• godot-performance-optimization — ピアの負荷によって帯域幅／CPU の予算が超過した場合に、レプリケーションレートを制限し、関心対象を絞り込みます。

マスター

• godot-master — このドメインスキルのライブラリルーターであり、ミラーされたモジュールのエントリです。