UnityServiceAdapter

Internal concrete implementation of IServiceAdapter using Unity Gaming Services. Handles SDK initialization, anonymous authentication, and session management via UGS Authentication and Multiplayer packages.

Definition

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

internal class UnityServiceAdapter : IServiceAdapter

Implements: IServiceAdapter

Remarks

UnityServiceAdapter is the default (and currently only) service adapter. It is instantiated by NetworkService when Connect() is called with NetworkServiceType.UNITY.

The adapter wraps three Unity Gaming Services APIs:

1. UnityServices (com.unity.services.core) — One-time SDK initialization via InitializeAsync().

2. AuthenticationService (com.unity.services.authentication) — Anonymous sign-in producing a player ID and name.

3. MultiplayerService (com.unity.services.multiplayer) — Session creation, joining, and querying with automatic relay networking.

All sessions are created with WithRelayNetwork() enabled, meaning Unity Relay handles NAT traversal transparently. After creating or joining a session, the adapter waits for the Netcode client connection (NetworkManager.WaitForClientConnection()) and player synchronization before returning.

Quick Lookup

Goal	How
Initialize UGS SDK	await adapter.Initialize()
Authenticate anonymously	await adapter.SignIn() → NetworkUser
Create a relay session	await adapter.CreateSession("My Session", 4)
Join by session ID	await adapter.JoinSession(sessionId)
Query available sessions	await adapter.QuerySessions()
Sign out	await adapter.SignOut()

Properties

ServiceType

Returns NetworkServiceType.UNITY.

public NetworkServiceType ServiceType => NetworkServiceType.UNITY;

Constructor

internal UnityServiceAdapter(NetworkService service)

Parameter	Type	Description
service	NetworkService	The parent service instance that owns this adapter

Methods

Initialize

Captures Unity's main thread context via UnityThreadUtils and initializes the UGS SDK.

public async Task Initialize()

Behavior:

1. Calls UnityThreadUtils.CaptureUnityThreadInfo() to ensure async continuations run on the Unity main thread.

2. Calls await UnityServices.InitializeAsync() to initialize the UGS SDK.

SignIn

Authenticates the local user anonymously via UGS Authentication.

public async Task<NetworkUser> SignIn()

Returns: A NetworkUser with the authenticated player's ID and display name (defaults to "Guest" if no name is set).

Behavior:

1. In the Unity Editor, clears the session token first (ClearSessionToken()) to force a fresh sign-in each session.

2. Calls AuthenticationService.Instance.SignInAnonymouslyAsync().

3. Reads PlayerId and PlayerName from the authentication instance.

SignOut

Signs the local user out and waits for the operation to complete.

public async Task SignOut()

Behavior:

• Uses a TaskCompletionSource<bool> to convert the event-based AuthenticationService.SignedOut callback into an awaitable Task.

• Calls SignOut(true) to clear credentials.

QuerySessions

Queries UGS Multiplayer for available sessions.

public async Task<List<NetworkSessionInfo>> QuerySessions(QuerySessionsOptions queryOptions = null)

Parameter	Type	Description
queryOptions	QuerySessionsOptions	Optional filter/sort criteria. Defaults to an empty options object.

Returns: A list of NetworkSessionInfo structs mapped from UGS session results.

CreateSession

Creates a new multiplayer session with Unity Relay networking enabled.

public async Task<NetworkSession> CreateSession(string sessionName, int maxConnections = max_connections)

Parameter	Type	Description
sessionName	string	Display name for the session. Defaults to "Paragon Session" if null.
maxConnections	int	Maximum players allowed. Defaults to 4.

Returns: A UnityNetworkSession wrapping the created UGS session.

Behavior:

1. Creates SessionOptions with the specified name and max players.

2. Calls MultiplayerService.Instance.CreateSessionAsync(sessionOptions.WithRelayNetwork()).

3. Waits for the Netcode client connection via NetworkManager.WaitForClientConnection().

4. Creates and returns a UnityNetworkSession via UnityNetworkSession.Create(session).

JoinSession

Joins an existing session by its unique identifier.

public async Task<NetworkSession> JoinSession(string sessionID)

Parameter	Type	Description
sessionID	string	The unique identifier of the session to join

Returns: A UnityNetworkSession wrapping the joined UGS session.

Behavior:

1. Calls MultiplayerService.Instance.JoinSessionByIdAsync(sessionID).

2. Waits for the Netcode client connection via NetworkManager.WaitForClientConnection().

3. Creates and returns a UnityNetworkSession via UnityNetworkSession.Create(session).

Constants

max_connections

Default maximum number of players per session.

private const int max_connections = 4;

Common Pitfalls

Editor session token In the Unity Editor, ClearSessionToken() is called before sign-in to prevent reusing stale tokens between play sessions. This is guarded by #if UNITY_EDITOR and does not affect builds.

Relay network required All sessions are created with WithRelayNetwork(). Direct peer-to-peer connections are not supported by this adapter. Ensure the Unity Relay package is installed and configured in the UGS dashboard.

Initialization order UnityThreadUtils.CaptureUnityThreadInfo() must be called before UnityServices.InitializeAsync(). Skipping the thread capture may cause async continuations to deadlock or execute on the wrong thread.

See Also

• IServiceAdapter — interface this class implements

• UnityNetworkSession — session implementation created by this adapter

• UnityThreadUtils — thread context utility used during initialization

• Unity Adapters — subsystem overview