NetworkSession

Abstract base class that manages multiplayer session state. Tracks connected players, handles connection approval, and synchronizes join/leave events across all clients using the Paragon messaging system. Platform-specific network services subclass this to implement session creation, leaving, and player kicking.

Definition

Namespace: Paragon.Core.Network Assembly: Paragon.dll

public abstract class NetworkSession

Remarks

NetworkSession is the core abstraction for multiplayer sessions. It operates on an owner-authoritative model:

• The session owner (host) handles connection approval, maintains the authoritative player list, and broadcasts join/leave events to all other clients.

• Non-owner clients receive the initial player list via SynchronizationMessage and subsequent updates via PlayerJoinedMessage / PlayerLeftMessage.

The constructor automatically subscribes to Netcode client callbacks and Paragon network messages. The session considers itself synchronized immediately if the current player is the owner; otherwise, it waits for a SynchronizationMessage from the owner.

Connection approval is delegated to OnConnectionApproval, which rejects duplicate users (same service ID already in session) and queues approved connections as PendingConnection records until the Netcode OnClientConnected callback fires.

Quick Lookup

Goal	How
Get session ID	session.Id
Get session name	session.Name
Check if local player owns session	session.IsOwner
Get all connected players	session.Players
Get the session owner	session.Owner
Find a player by client ID	session.GetPlayer(clientId)
Find a player by user ID	session.GetPlayer(userId)
Check if a player is connected	session.HasPlayer(clientId) or session.HasPlayer(userId)
Leave the session	await session.Leave()
Kick a player (owner only)	await session.KickPlayer(player)
Listen for player joins	session.PlayerJoined += OnPlayerJoined
Listen for player departures	session.PlayerLeft += OnPlayerLeft
Tear down the session	session.Shutdown()

Properties

Id

The unique identifier for this session.

public string Id { get; }

Name

The display name of this session.

public string Name { get; }

MaxConnections

The maximum number of players allowed in this session.

public int MaxConnections { get; }

Data

Custom key-value metadata associated with the session.

public Dictionary<string, string> Data { get; }

Players

The set of all currently connected players.

public HashSet<NetworkPlayer> Players { get; }

Owner

The NetworkPlayer who owns (hosts) this session.

public NetworkPlayer Owner { get; }

CurrentPlayer

The NetworkPlayer representing the local client.

public NetworkPlayer CurrentPlayer { get; }

IsOwner

Whether the local client is the session owner.

public bool IsOwner { get; }

Events

PlayerJoined

Raised when a new player joins the session (on all clients).

public Action<NetworkPlayer> PlayerJoined

PlayerLeft

Raised when a player leaves the session (on all clients).

public Action<NetworkPlayer> PlayerLeft

Methods

Constructor

protected NetworkSession(string id, string name, int maxConnections, string ownerID, Dictionary<string, string> data)

Parameter	Type	Description
id	string	Unique session identifier
name	string	Display name of the session
maxConnections	int	Maximum allowed players
ownerID	string	User ID of the session owner
data	Dictionary<string, string>	Custom session metadata

Initializes session state, creates the local NetworkPlayer, subscribes to Netcode callbacks (OnClientConnectedCallback, OnClientDisconnectCallback) and Paragon messages (SynchronizationMessage, PlayerJoinedMessage, PlayerLeftMessage).

Leave (abstract)

Leaves the current session. Implementation is platform-specific.

public abstract Task Leave()

KickPlayer (abstract)

Kicks a player from the session. Implementation is platform-specific.

public abstract Task KickPlayer(NetworkPlayer player)

Parameter	Type	Description
player	NetworkPlayer	The player to remove from the session

HasPlayer

Checks whether a player with the given identifier is in the session.

public bool HasPlayer(ulong clientID)
public bool HasPlayer(string userID)

Parameter	Type	Description
clientID	ulong	The Netcode client ID to search for
userID	string	The service user ID to search for

Returns: true if a matching player is in the session.

GetPlayer

Retrieves a player by identifier. Throws if not found.

public NetworkPlayer GetPlayer(ulong clientID)
public NetworkPlayer GetPlayer(string userID)

Parameter	Type	Description
clientID	ulong	The Netcode client ID to search for
userID	string	The service user ID to search for

Returns: The matching NetworkPlayer.

OnConnectionApproval

Called by the Netcode connection approval handler. Validates incoming connections and queues approved clients as pending.

public void OnConnectionApproval(
    NetworkManager.ConnectionApprovalRequest request,
    NetworkManager.ConnectionApprovalResponse response)

Parameter	Type	Description
request	ConnectionApprovalRequest	The incoming connection request with payload
response	ConnectionApprovalResponse	The response to approve or reject

Shutdown

Clears all session state and unsubscribes from Netcode callbacks. Call this when the session ends.

public void Shutdown()

ToString

Returns a string representation of the session.

public override string ToString()

Returns: "id - (name)"

Extension Points

Required Overrides

Method	Purpose
Leave()	Platform-specific session departure logic
KickPlayer(NetworkPlayer)	Platform-specific player removal logic

Optional Overrides

Method	Purpose
OnSynchronizationMessage(SynchronizationMessage)	Customize how the player list is rebuilt on sync. Call base to preserve default behavior.
OnPlayerJoined(NetworkPlayer)	React to a player joining. Call base to add to Players and broadcast the event.
OnPlayerLeft(NetworkPlayer)	React to a player leaving. Call base to remove from Players and broadcast the event.

Implementation Requirements

When subclassing NetworkSession, you MUST:

1. Implement Leave() to handle platform-specific session departure

2. Implement KickPlayer() to handle platform-specific player removal

3. Call base.OnPlayerJoined() / base.OnPlayerLeft() if overriding those methods (to maintain player tracking and event broadcasting)

4. Call base.OnSynchronizationMessage() if overriding (to rebuild the player list)

You SHOULD:

• Call Shutdown() when the session is no longer needed to avoid callback leaks

• Subscribe to PlayerJoined / PlayerLeft events for game-level reactions

Common Pitfalls

Forgetting to call Shutdown() The constructor subscribes to Netcode callbacks. If Shutdown() is never called, the session will continue receiving callbacks after it should have been disposed, leading to errors on stale player references.

GetPlayer throws on missing player GetPlayer() uses Enumerable.First() internally, which throws InvalidOperationException if no match is found. Use HasPlayer() first if the player may not exist.

Owner-only operations Connection approval, SynchronizationMessage broadcasting, and PlayerJoinedMessage / PlayerLeftMessage broadcasting only execute on the session owner. Non-owner clients receive these messages passively. Do not call OnConnectionApproval on non-owner clients.

Examples

Subscribing to Session Events

NetworkSession session = NetworkManager.Service.Session;

session.PlayerJoined += player =>
{
    Debug.Log($"{player.UserName} joined the session!");
};

session.PlayerLeft += player =>
{
    Debug.Log($"{player.UserName} left the session.");
};

Querying Players

// Check if a specific user is in the session
if (session.HasPlayer(userId))
{
    NetworkPlayer player = session.GetPlayer(userId);
    Debug.Log($"Found {player.UserName} (Client {player.ClientID})");
}

// Iterate all players
foreach (NetworkPlayer player in session.Players)
{
    Debug.Log($"{player.UserName}: {player.ClientID}");
}

Implementing a Custom Session

public class MyPlatformSession : NetworkSession
{
    public MyPlatformSession(string id, string name, int maxConnections,
        string ownerID, Dictionary<string, string> data)
        : base(id, name, maxConnections, ownerID, data) { }

    public override async Task Leave()
    {
        // Platform-specific leave logic
        await MyPlatformAPI.LeaveSession(Id);
        Shutdown();
    }

    public override async Task KickPlayer(NetworkPlayer player)
    {
        // Platform-specific kick logic
        await MyPlatformAPI.KickPlayer(Id, player.UserID);
    }

    protected override void OnPlayerJoined(NetworkPlayer player)
    {
        base.OnPlayerJoined(player);
        // Custom join handling
        MyGameUI.ShowJoinNotification(player.UserName);
    }
}

See Also

• NetworkSessionInfo — lightweight struct describing session metadata

• NetworkPlayer — record linking user identity with network client

• NetworkManager — the network system entry point that creates sessions