Connection & Matchmaking

Before any game objects can sync, players must connect to a server and be grouped into a shared session. Photon uses a two-tier architecture: clients first connect to a master server for matchmaking, then get routed to a game server hosting a room. A room is an isolated session where a fixed group of players share game state, exchange RPCs and replicate objects.

This page covers the full connection lifecycle, from initialization and server connection through room creation, joining and disconnection.

Initialization

Call initialize_from_settings() to load the App ID and version from Project Settings, or pass them explicitly.

GDScript

# From Project Settings (recommended)
FusionClient.initialize_from_settings()

# Or with explicit parameters
FusionClient.initialize("your-app-id", "1.0")

Connecting

Use connect_to_server() to initialize and connect in one call. All parameters are optional. Empty values are filled from Project Settings:

GDScript

# Simplest: everything from Project Settings
FusionClient.connect_to_server()

# With a specific user ID
FusionClient.connect_to_server("player_123")

# With a specific region (forces Cloud mode)
FusionClient.connect_to_server("player_123", "us")

Connection mode (Cloud vs Local) is determined by Project Settings > Fusion > Connection > Mode unless a region is explicitly provided.

Connecting and Joining

Connecting and joining are separate steps. Connect to the Photon master server first, then join or create a room once the connection succeeds.

GDScript

FusionClient.connect_to_server("player_123", "us")

# Wait for connection, then join
FusionClient.connected_to_server.connect(func():
    FusionClient.join_or_create_room("lobby")
)

For local development, set fusion/connection/mode to Local in Project Settings.

Room Operations

A room is a shared session where players sync objects and exchange RPCs. FusionClient provides methods to create, join or leave rooms.

GDScript

# Create a new room (fails if it already exists)
FusionClient.create_room("my_room", options)

# Join an existing room (empty name = random room)
FusionClient.join_room("my_room", options)

# Join if exists, create if not
FusionClient.join_or_create_room("my_room", options)

# Leave current room (stays connected for re-matchmaking)
FusionClient.leave_room()

The options parameter is an optional Dictionary. Omit it or pass {} for defaults.

Room Options

Pass an options Dictionary to customize room behavior when creating or joining.

Connection Status

FusionClient tracks a linear state machine from disconnected through connecting, connected, joining and finally in-room.

• STATUS_DISCONNECTED (0) - not connected
• STATUS_CONNECTING (1) - establishing connection
• STATUS_CONNECTED (2) - connected to master server, can join rooms
• STATUS_JOINING_ROOM (3) - join in progress
• STATUS_IN_ROOM (4) - in a room, can spawn and sync
• STATUS_ERROR (5) - connection error

Query methods: is_initialized(), is_connected_to_server(), is_in_room(), is_master_client(), get_local_player_id(), get_network_time().

Signals

Use signals to react to connection and room events without polling status each frame.

• room_joined - successfully entered a room (safe to spawn objects)
• room_left - left a room (voluntarily or disconnected)
• connection_failed(error: String) - connection attempt failed
• connection_status_changed(status: int) - status changed
• connected_to_server - connected to master server
• scene_load_requested(index: int, path: String) - scene change requested (CUSTOM load mode)
• scene_ready(index: int) - all scene objects registered after load
• scene_unloaded(index: int, path: String) - scene unloaded

Disconnecting

Call disconnect_from_server() to cleanly leave the current room and close the server connection.

GDScript

FusionClient.disconnect_from_server()

Example

A complete script that connects to Photon Cloud, joins a room with custom options and prints when the player enters.

GDScript

extends Node

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

    FusionClient.connect_to_server("player_%d" % randi())

    FusionClient.connected_to_server.connect(func():
        FusionClient.join_or_create_room("lobby", {
            "max_players": 8,
            "is_visible": true,
            "map": "arena",
            "lobby_properties": ["map"],
        })
    )

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