> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Multiplayer matchmaking with SmartMatch and MPM

> Use Multiplayer Manager and SmartMatch matchmaking to find XBOX Live players, create a lobby session, send optional invites, and start a multiplayer match.

<a id="top" />

This topic describes the basic steps that you need to implement SmartMatch matchmaking by using Multiplayer Manager.

A player might not have enough friends online when they want to play a game, or they just want to play against random players online.
You can use the SmartMatch service to find other XBOX players.

## Find a match

The following steps use Multiplayer Manager to send an invite to a player's friend so that friend can join the game in progress.

1. [Initialize Multiplayer Manager](#initialize-multiplayer-manager)
2. [Create the lobby session by adding local users](#create-lobby)
3. [Send invites to friends (optional)](#send-invites)
4. [Accept invites (optional)](#accept-invites)
5. [Find a match](#find-match)

Steps 1, 2, 3, and 5 are done on the device that's performing the invite.
Step 4 is typically initiated on the invitee's device, following app launch via protocol activation.

For more information, see [Playing a game by using SmartMatch matchmaking (flowchart)](/services/xbox-services/multiplayer/mpm/concepts/flowcharts/live-mpm-play-with-smartmatch-matchmaking).

## Initialize Multiplayer Manager <a id="initialize-multiplayer-manager" />

The lobby session object is automatically created when Multiplayer Manager is initialized with a valid session template name. Session templates are defined in the service configuration.

<Note>The lobby session instance on the service isn't created until a user has been added.</Note>

### Flat C API

```cpp theme={null}
HRESULT hr = XblMultiplayerManagerInitialize(lobbySessionTemplateName, queueUsedByMultiplayerManager);
```

For more information, see [XblMultiplayerManagerInitialize](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerinitialize).

[Return to the top of this topic.](#top)

## Create the lobby session by adding local users<a id="create-lobby" />

Add the locally signed-in XBOX services users to the lobby session.
A new lobby is hosted when the first user is added.
All other users are added to the existing lobby as secondary users.

Multiplayer Manager advertises the lobby in the shell for friends to join.
You can send invites, set lobby properties, and access lobby members only after you've added the local user.

When a local user joins the lobby, we recommend setting their connection address and any custom properties.

You must repeat this process for all locally signed-in users.

### Add a single local user

#### Flat C API

```cpp theme={null}
HRESULT hr = XblMultiplayerManagerLobbySessionAddLocalUser(xblUserHandle);

if (!SUCCEEDED(hr))
{
    // Handle failure.
}

// Set member connection address.
const char* connectionAddress = "1.1.1.1";
hr = XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress(
    xblUserHandle, connectionAddress, context);

if (!SUCCEEDED(hr))
{
    // Handle failure.
}

// Set custom member properties.
const char* propName = "Name";
const char* propValueJson = "{}";
hr = XblMultiplayerManagerLobbySessionSetProperties(propName, propValueJson, context);

if (!SUCCEEDED(hr))
{
    // Handle failure.
}
...
```

For more information, see the following:

* [XblMultiplayerManagerLobbySessionAddLocalUser](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionaddlocaluser)
* [XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionsetlocalmemberconnectionaddress)
* [XblMultiplayerManagerLobbySessionSetProperties](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionsetproperties)

[Return to the top of this topic.](#top)

### Add multiple local users

#### Flat C API

```cpp theme={null}
std::vector<XblUserHandle> xblUsers;
for (XblUserHandle xblUserHandle : xblUsers)
{
    HRESULT hr = XblMultiplayerManagerLobbySessionAddLocalUser(xblUserHandle);

    if (!SUCCEEDED(hr))
    {
        // Handle failure.
    }

    // Set member connection address.
    const char* connectionAddress = "1.1.1.1";
    hr = XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress(
        xblUserHandle, connectionAddress, context);

    if (!SUCCEEDED(hr))
    {
        // Handle failure.
    }

    // Set custom member properties.
    const char* propName = "Name";
    const char* propValueJson = "{}";
    hr = XblMultiplayerManagerLobbySessionSetProperties(propName, propValueJson, context);
    ...
}
```

For more information, see the following:

* [XblMultiplayerManagerLobbySessionAddLocalUser](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionaddlocaluser)
* [XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionsetlocalmemberconnectionaddress)
* [XblMultiplayerManagerLobbySessionSetProperties](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionsetproperties)

The changes are batched on the next [XblMultiplayerManagerDoWork](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork) call.
Multiplayer Manager fires an [XblMultiplayerEventType](/reference/live/xsapi-c/multiplayer_manager_c/enums/xblmultiplayereventtype)`::UserAdded` event each time a local user is added to the lobby session.

We recommend that you check the error code of the event to see if that user was successfully added.
In case of a failure, an error message provides details of the reasons for the failure.

Multiplayer Manager performs the following functions to create the lobby session by adding local users.

* Register Real Time-Activity and multiplayer subscriptions with the XBOX services multiplayer service.
* Create the lobby session.
* Join all local players as active.
* Upload secure device address (SDA).
* Set member properties.
* Register for session change events.
* Set the lobby session as an active session.

[Return to the top of this topic.](#top)

## Send invites to friends (optional) <a id="send-invites" />

Display the standard XBOX UI where the player can select friends or recent players to invite to the game.
When the player confirms their selection, Multiplayer Manager sends the invites to the selected players.

Games can also use the [XblMultiplayerManagerLobbySessionInviteUsers](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessioninviteusers) method to send invites to a set of players who are defined by their XBOX services User IDs.
This method is useful if you use your own in-game UI instead of the standard XBOX UI.

#### Flat C API

```cpp theme={null}
size_t xuidsCount = 1;
uint64_t xuids[1] = {};
xuids[0] = 1234567891234567;
HRESULT hr = XblMultiplayerManagerLobbySessionInviteUsers(
    xblUserHandle, 
    xuids, 
    xuidsCount, 
    nullptr,    // ContextStringId 
    nullptr     // CustomActivationContext
);
```

For more information, see [XblMultiplayerManagerLobbySessionInviteUsers](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessioninviteusers).

Multiplayer Manager performs the following functions to send invites to friends.

* Displays the XBOX standard title-callable UI (TCUI)
* Sends an invite directly to the selected players

[Return to the top of this topic.](#top)

## Accept invites (optional) <a id="accept-invites" />

When an invited player accepts a game invite or joins a friend's game via a shell UI, the game is launched on their device by using protocol activation.
After the game starts, Multiplayer Manager can use the protocol-activated event arguments to join the lobby.

If the invited user isn't added via [XblMultiplayerManagerLobbySessionAddLocalUser](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionaddlocaluser), [XblMultiplayerManagerJoinLobby](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoinlobby) fails and provides the xuid for which the invite was sent by calling [XblMultiplayerEventArgsXuid](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayereventargsxuid) with the `JoinLobbyCompleted` event.

After joining the lobby, we recommend setting the local member's connection address and any custom properties for the member.
You can also set the host via [XblMultiplayerManagerLobbySessionSetSynchronizedHost](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionsetsynchronizedhost) if one doesn't exist.

Finally, Multiplayer Manager will auto-join the user into the game session if a game is already in progress and has room for the invitee.
The title is notified through the `JoinGameCompleted` event, providing an appropriate error code and message.

Error or success results are handled via the `JoinLobbyCompleted` event.

#### Flat C API

```cpp theme={null}
HRESULT hr = XblMultiplayerManagerJoinLobby(inviteHandleId, xblUserHandle);
if (!SUCCEEDED(hr))
{
    // Handle failure.
}

// Set member connection address.
const char* connectionAddress = "1.1.1.1";
hr = XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress(
    xblUserHandle, connectionAddress, context);
```

For more information, see the following:

* [XblMultiplayerManagerJoinLobby](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoinlobby)
* [XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionsetlocalmemberconnectionaddress)

Multiplayer Manager performs the following functions to accept invites.

* Register Real-Time Activity and multiplayer subscriptions.
* Join lobby session.
* Existing lobby state cleanup.
* Join all local players as active.
* Upload SDA.
* Set member properties.
* Register for session change events.
* Set lobby session as active session.
* Join game session (if one exists).
* Use transfer handle.

### Find match <a id="find-match" />

After invites have been accepted and the host is ready to start playing the game, you can use SmartMatch to do one of the following:

* Find an existing game that has enough open player slots for all the members in the lobby session by calling [XblMultiplayerManagerFindMatch](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerfindmatch).
* Create a new game session that includes all the members in the lobby session, and fill open slots with other players who are looking for a match of the same game type, by calling [XblMultiplayerManagerJoinGameFromLobby](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoingamefromlobby) followed with [XblMultiplayerManagerAutoFillMembersDuringMatchmaking](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerautofillmembersduringmatchmaking).

Before you can call [XblMultiplayerManagerFindMatch](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerfindmatch), you must first configure hoppers in your service configuration.
A hopper defines the rules that SmartMatch uses to match players.

#### Flat C API

```cpp theme={null}
uint32_t timeoutInSeconds = 30;
HRESULT hr = XblMultiplayerManagerFindMatch(hopperName, attributesJson, timeoutInSeconds);
if (!SUCCEEDED(hr))
{
    // Handle failure.
}
```

For more information, see [XblMultiplayerManagerFindMatch](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerfindmatch).

Multiplayer Manager performs the following functions to find a match.

* Create a match ticket.
* Handle all the Quality of Service (QoS) stages.
* Handle roster changes.
* Resubmit (if needed).
* Join target game session.
* Advertise game via lobby session.

[Return to the top of this topic.](#top)


## Related topics

- [Playing a game by using SmartMatch matchmaking (flowchart)](/services/xbox-services/multiplayer/mpm/concepts/flowcharts/live-mpm-play-with-smartmatch-matchmaking.md)
- [SmartMatch matchmaking](/services/xbox-services/multiplayer/matchmaking/live-matchmaking-nav.md)
- [Using SmartMatch matchmaking](/services/xbox-services/multiplayer/matchmaking/concepts/live-matchmaking-how-tos.md)
- [Configuring matchmaking in Partner Center](/services/xbox-services/multiplayer/matchmaking/config/live-matchmaking-config.md)
- [Multiplayer concepts overview](/services/xbox-services/multiplayer/concepts/live-multiplayer-concepts.md)