Edit

Create a lobby

  • Article

This article explains how to create a lobby.

How are lobbies created?

There are several ways a lobby can be created.

  • By your players: Lobbies can be created by players who want get together a team of players to play. These are client-owned lobbies.
  • By your game servers: Your title's game servers can create lobbies and wait for players to join. These are server-owned lobbies.
  • By matchmaking: After a group of players form after matchmaking, a lobby is created as a holding place before the game starts. These are client-owned lobbies.

From a technical perspective, all lobbies are fall into two main categories based on ownership—server-owned and client-owned. To learn more, see Owner requirements and privileges.

The general usage of PlayFab Lobby is to temporarily hold a group of players together. For commonly used applications of Lobby, see the Azure PlayFab Lobby overview.

Supported entity types

Before a lobby can be created, your title must login as a PlayFab entity.

How lobbies are configured

Several important settings for a lobby are configured during creation: maxMemberCount, accessPolicy, owner, and ownerMigrationPolicy.

  • maxMemberCount defines how many players the lobby can hold
  • accessPolicy defines who may discover the lobby's connection string
  • owner defines the lobby's owner which has special permissions to update data on the lobby. This value is implicitly the client or server entity who is creating the lobby.
  • ownerMigrationPolicy defines policies for how ownership of the lobby should be transferred if the current owner leaves the lobby or has trouble maintaining a connection to the lobby.

Additionally, during creation, the lobby creator can also define custom lobby properties and search properties to append custom data to the lobby session. These custom properties can also be modified over the lifetime of the lobby by the lobby's owner.

For more information, see Lobby properties.

Example creating a client-owned lobby using the Lobby and Matchmaking SDK

This example uses a local player who has been logged into PlayFab as a title_player_account entity.

In this code snippet, Lobby properties are passed in as lobbyConfiguration and the player creating the lobby passes in their initial member properties via creatorMemberConfiguration. The local player becomes the lobby owner, so it's a client-owned lobby. After the lobby is successfully created, the PFLobbyHandle can be used to invite other players with PFLobbySendInvite.

    // Retrieved elsewhere from SDK's PFMultiplayerInitialize API
    PFMultiplayerHandle apiHandle = g_pfmHandle;

    // Retrieved elsewhere from one of PlayFab's title_player_account login APIs
    const PFEntityKey* clientOwner = m_localPlayerTitlePlayerAccounts[0];

    // Initialize the lobby configuration
    const char* gameModePropertyKey = "GameMode";
    const char* gameModePropertyValue = "GameMode_Foo";

    PFLobbyCreateConfiguration lobbyConfiguration{};
    lobbyConfiguration.maxMemberCount = 16;
    lobbyConfiguration.ownerMigrationPolicy = PFLobbyOwnerMigrationPolicy::Automatic;
    lobbyConfiguration.accessPolicy = PFLobbyAccessPolicy::Private;
    lobbyConfiguration.lobbyPropertyCount = 1;
    lobbyConfiguration.lobbyPropertyKeys = &gameModePropertyKey;
    lobbyConfiguration.lobbyPropertyValues = &gameModePropertyValue;
    
    // Initialize the creator's member properties
    const char* playerColorPropertyKey = "PlayerColor";
    const char* playerColorPropertyValue = "Red";

    PFLobbyJoinConfiguration creatorMemberConfiguration{};
    creatorMemberConfiguration.memberPropertyCount = 1;
    creatorMemberConfiguration.memberPropertyKeys = &playerColorPropertyKey;
    creatorMemberConfiguration.memberPropertyValues = &playerColorPropertyValue;

    // Create a lobby using our first player
    PFLobbyHandle lobby;
    HRESULT error = PFMultiplayerCreateAndJoinLobby(
        apiHandle,
        clientOwner,
        &lobbyConfiguration,
        &creatorMemberConfiguration,
        nullptr,
        &lobby);

When the call to create a lobby completes, a PFLobbyCreateAndJoinLobbyCompletedStateChange will be provided by PFMultiplayerStartProcessingLobbyStateChanges.

Example creating a server-owned lobby using the Lobby and Matchmaking SDK

This example is similar to the client-owned lobby example except that it creates the lobby as a game_server entity and PFMultiplayerCreateAndClaimServerLobby is called in place of PFMultiplayerCreateAndJoinLobby.

    // Retrieved elsewhere from SDK's PFMultiplayerInitialize API
    PFMultiplayerHandle apiHandle = g_pfmHandle;

    // Retrieved elsewhere from one of PlayFab's game_server login APIs
    const PFEntityKey* serverOwner = m_gameServerEntityKey;

    const char* gameModePropertyKey = "GameMode";
    const char* gameModePropertyValue = "GameMode_Foo";
    
    // Initialize the lobby configuration
    PFLobbyCreateConfiguration lobbyConfiguration{};
    lobbyConfiguration.maxMemberCount = 16;
    lobbyConfiguration.ownerMigrationPolicy = PFLobbyOwnerMigrationPolicy::Automatic;
    lobbyConfiguration.accessPolicy = PFLobbyAccessPolicy::Public;
    lobbyConfiguration.lobbyPropertyCount = 1;
    lobbyConfiguration.lobbyPropertyKeys = &gameModePropertyKey;
    lobbyConfiguration.lobbyPropertyValues = &gameModePropertyValue;
    
    // Create a lobby using our first player
    PFLobbyHandle lobby;
    HRESULT error = PFMultiplayerCreateAndClaimServerLobby(
        apiHandle,
        serverOwner,
        &lobbyConfiguration,
        nullptr,
        &lobby);

When the call to create a lobby completes, a PFLobbyCreateAndClaimServerLobbyCompletedStateChange will be provided by PFMultiplayerStartProcessingLobbyStateChanges.

For more information on the differences between client-owned lobbies and server-owned lobbies, see Game Servers and Lobbies.

Note

To enable the game server APIs in PlayFab Multiplayer, you must define PFMULTIPLAYER_INCLUDE_SERVER_APIS before including PFLobby.h. For more information, see Game Servers and Lobbies

See also