接続とマッチメイキング

ゲームオブジェクトを同期する前に、プレイヤーはまずサーバーへ接続して、共有セッションのグループに入る必要があります。Photonは2層アーキテクチャを採用していて、クライアントは最初にマッチメイキングのためにマスターサーバーへ接続し、その後にルームをホストするゲームサーバーへ転送されます。ルームは独立したセッションで、プレイヤーのグループがゲーム状態の共有・RPCの交換・オブジェクトの複製を行う場所になります。

このページでは、初期化・サーバーへの接続・ルーム作成/参加/切断を含む、接続ライフサイクル全体について説明します。

AppIDの設定

Fusionの接続にはPhotonのAppIDが必要です。この設定には2つの方法があります。

プロジェクト設定（推奨） — プロジェクト設定 > Fusion > Connectionからfusion/connection/app_idを設定します。これは標準的な方法で、ほとんどのプロジェクトで動作します。

実行時に上書き — 接続前にFusion.set_app_id("your-app-id")を呼び出します。AppIDが実行時に決定される場合（ビルドごとの設定・リモート設定・機能フラグ・その他プロジェクト設定に組み込めない状況）にはこれを使用してください。

GDScript

# 実行時に上書き — connect_to_photon()前に呼び出す必要がある
Fusion.set_app_id("my-runtime-app-id")

app_versionは、connect_to_photon()で明示的に値を渡さない場合は、常にプロジェクト設定（fusion/connection/app_version）から読み込まれます。

接続

connect_to_photon()を使用することで、Photon Cloudに接続できます。パラメーターはすべてオプションで、空の値はプロジェクト設定から読み込まれます：

GDScript

# すべてをプロジェクト設定から読み込む最もシンプルな形
Fusion.connect_to_photon()

# 特定のユーザーIDを指定
Fusion.connect_to_photon("player_123")

# 特定のリージョンを指定（Cloud接続モードを強制的に使用）
Fusion.connect_to_photon("player_123", "us")

ルーム操作

Photon Cloudへの接続が完了すると、connected_to_photonシグナルが発火します。そこからルームの作成/参加を行います。

ルームとは、プレイヤーがオブジェクトを同期したりRPCを交換したりするための共有セッションのことです。Fusionには、ルームの作成/参加/退出を行うメソッドが用意されています。

GDScript

Fusion.connect_to_photon("player_123", "us")

# 接続完了を待ち、それから参加する
Fusion.connected_to_photon.connect(func():
    # 新しいルームの作成（既に存在する場合は失敗）
    Fusion.create_room("my_room", options)

    # 既存のルームに参加（ルーム名を空にするとランダム参加）
    Fusion.join_room("my_room", options)

    # ルームが存在するなら参加、存在しないなら作成
    Fusion.join_or_create_room("my_room", options)
)

optionsパラメーターはFusionRoomOptions型です。省略するかnullを渡すと、デフォルト値が適用されます。

ルームオプション

ルームの作成/参加時に、ルームの動作をカスタマイズするFusionRoomOptionsインスタンスを渡すことができます。

キー	型	説明
max_players	int	ルームに参加できる最大プレイヤー数
is_visible	bool	ロビーのクエリにルームが表示されるかどうか
is_open	bool	ルームに新しいプレイヤーが参加できるかどうか
player_ttl_ms	int	使用されていないプレイヤースロットが解放されるまでの秒数（ミリ秒）
empty_room_ttl_ms	int	空のルームが破棄されるまでの秒数（ミリ秒）
lobby_properties	Array[String]	ロビーのリストに表示されるカスタムプロパティ
plugins	Array[String]	このルームでロードするサーバープラグイン名
custom_properties	Dictionary (bool, int, float, String)	ルームのカスタムプロパティ（例："map"・"game_mode"）

接続ステータス

Fusionは、切断状態・接続中・接続状態・参加中・ルーム内を含む、線形の状態遷移を追跡しています。

• STATUS_DISCONNECTED (0) - 未接続
• STATUS_CONNECTING_TO_PHOTON (1) - Photon Cloudへの接続を確立中
• STATUS_CONNECTED_TO_PHOTON (2) - Photon Cloud接続済み、ルーム参加可能
• STATUS_JOINING_ROOM (3) - 参加中
• STATUS_IN_ROOM (4) - ルーム内、スポーンや同期が可能
• STATUS_ERROR (5) - 接続エラー
• STATUS_DISCONNECTING (6) - Photon Cloudから切断中

クエリメソッド： is_initialized(), is_connected_to_photon(), is_in_room(), is_master_client(), get_local_player_id(), get_network_time()

シグナル

シグナルを使用することで、フレーム毎にステータスをポーリングすることなく、接続やルームのイベントに反応できます。

• room_joined - 正常にルームに入った（安全にオブジェクトをスポーン可能）
• room_left - ルームを抜けた（自発的 or 切断）
• connection_failed(error: String) - 接続の試行が失敗
• connection_status_changed(status: int) - ステータスが変更された
• connected_to_photon - Photon Cloudへ接続した
• disconnected_from_photon - Photon Cloudから切断した
• player_joined(player_id: int, user_id: String) - リモートプレイヤーがルームに参加した
• player_left(player_id: int, is_inactive: bool) - リモートプレイヤーがルームから抜けた（そのプレイヤーは、ルームのplayer_ttl_ms猶予期間中はis_inactiveがtrueとなり、再参加が可能）
• scene_load_requested(index: int, path: String) - シーン変更がリクエストされた（カスタムロードモード）
• scene_ready(index: int) - ロード後にすべてのシーンオブジェクトが登録された
• scene_unloaded(index: int, path: String) - シーンがアンロードされた

切断

disconnect_from_photon()を呼び出すと、現在のルームを退出してPhoton Cloud接続を閉じます。

GDScript

Fusion.disconnect_from_photon()

シングルプレイヤーモード

Fusionはオフラインシングルプレイヤーモードの実行にも対応しています。このモードでは、Fusionのノードやコードが、オンラインのルームに接続されているかのように動作します。

シングルプレイヤールームに入るには、Photon Cloudに接続していない状態でFusion.create_singleplayer_room()を呼び出してください。Fusionが既にPhoton cloudに接続している場合は、まずdisconnect_from_photon()を呼び出す必要があります。

GDScript

# Photon Cloud接続中は、シングルプレイヤールームを作成できないため、
# シングルプレイヤールームに入る前に、正常に切断されるまで待つ必要がある

if Fusion.is_connected_to_photon():
    Fusion.disconnect_from_photon()
    await Fusion.disconnected_from_photon
    
Fusion.create_singleplayer_room()

シングルプレイヤールームに入ると、FusionReplicator・RPC・FusionSpawner・シーンローディング・Fusionライフタイムシグナル（room_joined・player_joined・scene_readyなど）は、すべてオンラインのルームと同様に動作します。クライアントが現在シングルプレイヤールーム内にいるかどうかを確認するには、Fusion.is_singleplayer()を使用してください。

シングルプレイヤールーム内では、一部の機能の動作が若干異なります：

• Fusion.get_room()は、常にnullを返します。
• Fusion.get_local_player_id()は、常に1を返します。
• Fusion.get_network_time()はローカル時間となり、Engine.time_scaleとget_tree().pausedの影響を受けます。
• ローカルプレイヤーはすべての複製ノードに対して、常に権限（状態権限と入力権限）を持ちます：
  • FusionReplicator.has_authority()は、常にtrueを返します。
  • FusionReplicator.get_authority()は、常に1を返します。
  • FusionSharedReplicator.want_authority(bool)は、所有権モードにかかわらず、何も行いません。
  • FusionServerReplicator.has_input_authority()は、常にtrueを返します。
  • FusionServerReplicator.get_input_authority()は、常に1を返します。
  • FusionServerReplicator.set_input_authority(int)は何も行いません。

シングルプレイヤールームから切断するには、Fusion.leave_room()を使用してください。

実装例

Photon Cloudへ接続し、カスタムオプションを設定してルームに参加し、プレイヤー参加時にメッセージを表示するスクリプトの全容です。

GDScript

extends Node

func _ready():
    Fusion.room_joined.connect(_on_room_joined)
    Fusion.connection_failed.connect(func(e): print("Failed: ", e))

    Fusion.connect_to_photon.call_deferred("player_%d" % randi())

    Fusion.connected_to_photon.connect(func():
        var options := FusionRoomOptions.new()
        options.max_players = 8
        options.is_visible = true
        options.lobby_properties = ["map"]
        options.custom_properties = {"map": "arena"}
        Fusion.join_or_create_room("lobby", options)
    )

func _on_room_joined():
    print("In room as player ", Fusion.get_local_player_id())

Last updated on 27/10/2026

Back to top