Unity SDK

The SDK is in preview. Its networking core is covered by automated tests against the live API; the Unity and Mirror layers are new. Tell us what breaks.

Requires Unity 2021.3 or newer. No third-party dependencies; Mirror support is optional and only compiles when Mirror is installed.

Install

Package Manager → + → Add package from git URL with the URL we give you during onboarding, then create the settings asset: Assets → Create → Matchdock → Settings. Enter the API URL and your client key. The asset refuses a server key: those must never ship in a game.

Sign in

var client = MatchdockUnity.CreateClient(settings);
var result = await client.SignInAsync(
    MatchdockUnity.DeviceId,          // stable per installation
    MatchdockUnity.PlatformName,      // IOS, ANDROID, UNITY_EDITOR, UNKNOWN
    displayName: null,                // optional; a guest name is generated
    appVersion: Application.version);

Debug.Log($"{result.profile.displayName} · rating {result.profile.rating}");

The same device always maps to the same player. The session token is kept in PlayerPrefs; when it expires the SDK signs in again by itself and repeats the request once.

Find a match

matchmaking = new CancellationTokenSource();

var ticket = await new Matchmaker(client).FindMatchAsync(new FindMatchOptions {
    QueueName = "ranked",
    TimeoutSeconds = 120,
    OnStateChanged = state => statusLabel.text = state,   // SEARCHING, MATCH_FOUND, ...
}, matchmaking.Token);

FindMatchAsync resolves with a MatchTicket: Host, Port, JoinToken, Slot, MatchId, ServerSessionId and the Opponent. It leaves the queue for the player when the token is cancelled or the timeout passes, and rides out a few failed polls so a moment of bad mobile signal does not cost the player their place.

Cancel from a button or when the scene unloads:

void OnDestroy() => matchmaking?.Cancel();

Connect

Give the ticket to your netcode. With Mirror, add the Matchdock Authenticator component to your NetworkManager:

manager.networkAddress = ticket.Host;
((kcp2k.KcpTransport)Transport.active).Port = (ushort)ticket.Port;
manager.GetComponent<MatchdockAuthenticator>().SetTicket(client.UserId, ticket);
manager.StartClient();

The authenticator presents the join token; the server side verifies it with Matchdock before the player is allowed to spawn.

Everything else

Failures throw MatchdockException with the HTTP Status (0 means the request never reached us) and IsTransient, which is true for network trouble, rate limiting and server errors.