Connection and Room Lifecycle

Multiplayer uses a GamePush channel as a room. All players connecting with the same channelId join the same multiplayer session.

Method List

Actions:

• gp.multiplayer.connect() - connect to a multiplayer room. +1 Request
• gp.multiplayer.disconnect() - disconnect from the current room. +1 Request

Properties:

• gp.multiplayer.isConnected - check whether the player is connected. FREE
• gp.multiplayer.isHost - check whether the current player is the host. FREE
• gp.multiplayer.connectedPlayers - get connected players. FREE
• gp.multiplayer.networkStats - get current network diagnostics. FREE

Events:

• connect and disconnect - track the connection lifecycle.
• playerJoined and playerLeft - track room members.
• becameHost, becamePeer, and hostMigrated - track host role changes.
• error:connect, error:sendState, and error:disconnect - handle multiplayer errors.

Choose a Channel

Any channel can technically be used for multiplayer if:

• all players are channel members;
• the channel has available member slots;
• join requests for a private channel have already been accepted;
• all players connect using the same channelId.

In most games, create a separate channel for each lobby or match. The channel members then represent the players allowed to join that multiplayer room, while the channel privacy and capacity settings define the lobby access rules and maximum player count.

Avoid using a large public chat channel as a multiplayer room. Every channel member who connects with its channelId becomes part of the same multiplayer session.

See Manage Channels and Channel Members for channel creation, capacity, privacy, and membership settings.

Connect to a Room

Subscribe to lifecycle events, make sure the player is a channel member, and connect to the room:

JavaScript

const channelId = 123;

function onConnect({ success }) {
    console.log('Connected:', success);
}

function onDisconnect({ reason }) {
    console.log('Disconnected:', reason);
}

gp.multiplayer.on('connect', onConnect);
gp.multiplayer.on('disconnect', onDisconnect);

async function connectToRoom() {
    const channel = await gp.channels.fetchChannel({ channelId });

    if (!channel.isJoined) {
        await gp.channels.join({ channelId });
    }

    await gp.multiplayer.connect({ channelId });
}

await connectToRoom();

Unity

const int channelId = 123;

void OnConnect(GP_Data data)
{
    Debug.Log("Connected: " + data.Data);
}

void OnDisconnect(GP_Data data)
{
    Debug.Log("Disconnected: " + data.Data);
}

async void ConnectToRoom()
{
    GP_Multiplayer.on("connect", OnConnect);
    GP_Multiplayer.on("disconnect", OnDisconnect);

    await GP_Multiplayer.connect(new MultiplayerChannelQuery
    {
        channelId = channelId
    });
}

warning

Joining a private channel may only create a join request. Call gp.multiplayer.connect() after the request has been accepted and the player has become a channel member.

Calling connect() while already connected throws an error.

Current Connection State

Use isConnected to check the connection and isHost to check the current player's role:

JavaScript

gp.multiplayer.isConnected;
gp.multiplayer.isHost;

Unity

GP_Multiplayer.isConnected;
GP_Multiplayer.isHost;

The host is selected asynchronously. Use the role events to start and stop host-only logic:

JavaScript

gp.multiplayer.on('becameHost', startHostLogic);
gp.multiplayer.on('becamePeer', stopHostLogic);

Unity

GP_Multiplayer.on("becameHost", StartHostLogic);
GP_Multiplayer.on("becamePeer", StopHostLogic);

The hostMigrated event provides both player IDs:

JavaScript

gp.multiplayer.on('hostMigrated', ({ oldHost, newHost }) => {
    console.log(`Host changed from ${oldHost} to ${newHost}`);
});

Unity

void OnHostMigrated(GP_Data data)
{
    Debug.Log("Host migrated: " + data.Data);
}

GP_Multiplayer.on("hostMigrated", OnHostMigrated);

Connected Players

JavaScript

gp.multiplayer.connectedPlayers;

Unity

GP_Data connectedPlayers = GP_Multiplayer.connectedPlayers;
Debug.Log(connectedPlayers.Data);

Each item in connectedPlayers contains:

{
    playerId: 123,
    isHost: false,
    ping: 42,
    connectionStability: 1,
    sessionDuration: 15000,
}

Network Statistics

The SDK exposes current network diagnostics:

JavaScript

const {
    ping,
    bufferSize,
    bufferDelay,
} = gp.multiplayer.networkStats;

Unity

GP_Data networkStats = GP_Multiplayer.networkStats;
Debug.Log(networkStats.Data);

• ping is the current player's measured latency in milliseconds.
• bufferSize is the number of snapshots in the interpolation buffer.
• bufferDelay is the time range covered by buffered snapshots.

These values are useful for a debug panel and connection quality indicators.

Handle Errors

JavaScript

gp.multiplayer.on('error:connect', (error) => {
    console.error('Could not connect to multiplayer:', error);
});

gp.multiplayer.on('error:sendState', (error) => {
    console.error('Could not send multiplayer state:', error);
});

gp.multiplayer.on('error:disconnect', (error) => {
    console.error('Could not disconnect from multiplayer:', error);
});

Unity

void OnMultiplayerError(GP_Data error)
{
    Debug.LogError(error.Data);
}

GP_Multiplayer.on("error:connect", OnMultiplayerError);
GP_Multiplayer.on("error:sendState", OnMultiplayerError);
GP_Multiplayer.on("error:disconnect", OnMultiplayerError);

Disconnect and Clean Up

Stop game loops before disconnecting:

JavaScript

async function leaveRoom() {
    await gp.multiplayer.disconnect({ channelId });

    gp.multiplayer.off('connect', onConnect);
    gp.multiplayer.off('disconnect', onDisconnect);
}

Unity

async void LeaveRoom()
{
    await GP_Multiplayer.disconnect(new MultiplayerChannelQuery
    {
        channelId = channelId
    });

    GP_Multiplayer.off("connect", OnConnect);
    GP_Multiplayer.off("disconnect", OnDisconnect);
}

disconnect() does nothing if the player is not currently connected.

Stay in Touch

Other documents of this chapter are available here. To get started with GamePush, see the Tutorials chapter.

GamePush Community Telegram: @gs_community.

For your suggestions e-mail: official@gamepush.com

We Wish you Success!