# Introduction to multiplayer sessions

> Learn how multiplayer sessions manage connected players, session ownership, and game state in Unity Multiplayer Services.

Sessions provide an abstraction layer for managing connected players, session ownership, and gameplay state across multiplayer experiences. In Unity Multiplayer Services (MPS SDK), a session acts as the shared coordination point for players, host election, data updates, and connection setup.

A session represents a group of connected players and manages their interactions through different connection types, including client-hosted solutions like [Relay](/relay.md) and [Distributed Authority](https://unity.com/products/distributed-authority), or [dedicated game servers](/mps-sdk/game-server-hosting-support/.md). Sessions work with either the [Netcode for GameObjects](https://docs.unity3d.com/Packages/com.unity.netcode.gameobjects@latest) or the [Netcode for Entities](https://docs.unity3d.com/Packages/com.unity.netcode@latest) networking libraries.

## What sessions are

A session is the shared container that coordinates a multiplayer game. It keeps track of connected players, session metadata, and game state, and it exposes the operations needed to create, join, modify, and leave a multiplayer match.

The MPS SDK combines the underlying functionality of Lobby, Matchmaker, and Relay into a single API centered on sessions. This single interface reduces boilerplate code and standardizes UGS usage, automatically managing features like Lobby heartbeating and, when enabled, the Lobby/Relay integration, allowing developers to focus on unique game features.

The following diagram shows the flow for a typical session-based setup from the host's point of view point of view:

```mermaid
 sequenceDiagram
    participant Game Code
    participant Session SDK
    participant Lobby SDK
    participant Relay SDK
    participant Game Netcode

    Game Code->>Session SDK: Create session
    Session SDK->>Lobby SDK: Create lobby
    Session SDK->>Lobby SDK: Subscribe to lobby events
    loop Heartbeat
        Session SDK->>Lobby SDK: Heartbeat
    end
    Note over Session SDK,Lobby SDK: "Continue to heartbeat until the host<br/>leaves, deletes the lobby or the host changes."

    Session SDK->>Relay SDK: Create relay allocation
    Session SDK->>Lobby SDK: Setup lobby/relay integration for host
    Session SDK->>Lobby SDK: Update lobby with relay connection data

    Session SDK->>Game Netcode: Setup netcode with relay data
    Session SDK->>Game Netcode: Start host
    Session SDK-->>Game Code: Return session
```

## How sessions work

Sessions manage the lifecycle of a multiplayer match from creation to shutdown. They can create a lobby, assign a host, manage connection data, and handle player join and leave events as the session evolves.

The session model supports several important concepts:

* Session ownership: One player or service-owned session can act as the authoritative host for a match.
* Player membership: Each connected player is tracked as part of the session and can have per-player state.
* Connection setup: Sessions can use different networking options, depending on the runtime architecture you choose.
* Session data: Session metadata and player properties can change while the match is running.

When a session starts, the MPS SDK can create a lobby, allocate relay resources, and pass the relevant connection data to your networking layer. This reduces the amount of service-specific coordination you need to implement in your game code.

The following diagram shows the flow for a typical session-based setup from the client's point of view point of view:

```mermaid
  sequenceDiagram
    participant Game Code
    participant Session SDK
    participant Lobby SDK
    participant Relay SDK
    participant Game Netcode
    Game Code->>Session SDK: Join session
    Session SDK->>Lobby SDK: Join lobby
    Session SDK->>Lobby SDK: Subscribe to lobby events
    Note over Session SDK,Lobby SDK: "Unlike the host, a joining client<br/>never heartbeats the lobby."

    Session SDK->>Lobby SDK: Read host's relay connection data
    Session SDK->>Relay SDK: Join relay allocation
    Session SDK->>Lobby SDK: Update lobby with own player data

    Session SDK->>Game Netcode: Setup netcode with relay data
    Session SDK->>Game Netcode: Start client
    Session SDK-->>Game Code: Return session
```

## Session lifecycle and state

A session doesn't exist only as a container for players. It also manages state and behavior across the full match lifecycle. For example, the session can track player joins and departures, keep host ownership up to date, and support reconnection or migration when needed.

The lifecycle commonly includes:

1. Create or find a session.
2. Authenticate players and validate access.
3. Establish networking and connection data.
4. Start gameplay and update session information.
5. Handle disconnects, host migration, or session cleanup.

This SDK lets you focus on game logic while the session API manages the supporting multiplayer infrastructure.

For more information, refer to [Session states](./session-states.md)

## Session data

Sessions include the information needed to identify the match, track its current members, manage access rules, and connect players to the active network.

A session contains the following data:

* `Id`: The unique identifier for the session.
* `Code`: The generated join code that players can use to enter the session.
* `Name`: The human-readable name of the session.
* `Type`: The session type used to distinguish different session contexts and reconnect flows.
* `Host`: The player ID of the player currently holding host authority over the session.
* `Players`: The players currently in the session.
* `Properties`: The session-level metadata and state that the host or service can read and update.
* `State`: The current lifecycle state of the session.
* `MaxPlayers`: The maximum number of players allowed in the session.
* `PlayerCount` or `AvailableSlots`: The current occupancy or remaining capacity of the session.
* `IsPrivate`: Whether the session is hidden from public queries.
* `IsLocked`: Whether the session prevents additional players from joining.
* `HasPassword`: Whether a password is required to join the session.
* `Network`: The connection information used for relay or networking setup.

For more information, refer to [Session properties](./session-properties.md) and the [package documentation](https://docs.unity3d.com/Packages/com.unity.services.multiplayer@latest/index.html?subfolder=/api/Unity.Services.Lobbies.Models.Lobby.html#properties).

## When to use sessions

Use sessions when your game needs a shared multiplayer state with consistent player membership and service-managed coordination. Sessions are useful for games that need to do the following:

* Create a match and keep it organized around a single host or service-owned session.
* Let players join and leave without manually reworking lobby or relay setup.
* Share per-session or per-player data during the match.
* Coordinate networking flows between connection, matchmaking, and gameplay logic.

Sessions are especially useful when you want to unify Lobby, Matchmaker, and Relay behavior under one programming model while still retaining access to service-specific APIs when needed.

## Additional resources

* [Create a session](./create-session.md)
* [Find and join a session](./join-session.md)
* [Match players](./matchmake-session.md)
* [Manage session data](./mps-data-toc.md)
* [Monitor and debug sessions](./monitor-sessions-toc.md)
* [Connect players through a relay](./connect-players.md)

> **Important:**
>
> Starting with Multiplayer Services SDK version 1.2, the default network handler implementation for Netcode for Entities automatically creates client and server worlds if none are available when starting a network connection through sessions.
>
> Older versions of the MPS SDK require you to create your [Netcode for Entities client and server worlds](https://docs.unity3d.com/Packages/com.unity.netcode@latest/index.html?subfolder=/manual/client-server-worlds.html) before you can create or join a Multiplayer Services session. When you first add the Netcode for Entities package to your project, the [default bootstrap](https://docs.unity3d.com/Packages/com.unity.netcode@latest/index.html?subfolder=/manual/client-server-worlds.html#bootstrap) automatically creates the client and server worlds at startup.
>
> For more advanced use cases, use a [custom network handler](/mps-sdk/manage-session-network-connection.md.md#example:-using-a-custom-network-handler) to override the default integration with Netcode for Entities.