Skip to main content

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:

Properties:

Events:

Choose a Channel​

Multiplayer uses GamePush channels. To play with other channel members, a player must be a member of that channel.

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.

Choose a hub​

Channels, including multiplayer rooms, are hosted on the RU, EU, NA, and APAC hubs. To find an existing room before connect, use gp.channels.fetchChannels.

The location filter in fetchChannels limits the search to one hub. You can search with:

  • location: gp.player.location to use the hub recommended for the player based on the country of their request (available after player sync);
  • location: 'AUTO' to have the server choose a hub based on the country of the current request and return its channels;
  • location: 'RU' to search on the specific RU hub;
  • no location filter to search across all hubs.

Developers can use this search to implement region-based matchmaking or a screen listing channels available to the player. If no suitable rooms are found, the game decides what to do next: create a room, tell the player that no rooms are available, or search on other hubs.

In the channel template settings, you can select a fixed hub in the Location field. All channels created from that template will be hosted on the selected hub.

The filter is available in the JavaScript SDK. See Fetch List of Channels.

const { items } = await gp.channels.fetchChannels({
    tags: ['lobby'],
    location: gp.player.location, // or 'AUTO', 'RU', 'EU', 'NA', 'APAC'
    limit: 20,
});

const channel = items.find((item) => item.membersCount < item.capacity) || items[0];

if (!channel) {
    throw new Error('No lobby in this region');
}

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

await gp.multiplayer.connect({ channelId: channel.id });

Connect to a Room​

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

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();
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:

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

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

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

The hostMigrated event provides both player IDs:

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

Connected Players​

gp.multiplayer.connectedPlayers;

Each item in connectedPlayers contains:

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

Network Statistics​

The SDK exposes current network diagnostics:

const {
    ping,
    bufferSize,
    bufferDelay,
} = gp.multiplayer.networkStats;
  • 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​

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

Disconnect and Clean Up​

Stop game loops before disconnecting:

async function leaveRoom() {
    await gp.multiplayer.disconnect({ 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!