The GameIdentityRegistry Pattern — Bridging Mirror netId and Socket.IO playerId

When you run Mirror and Socket.IO in the same Unity project, you immediately hit a translation problem.

Mirror identifies players by netId — a uint assigned at spawn time by the Mirror host. Socket.IO identifies players by playerId — a string assigned by your Node.js backend when they connect.

These two IDs have nothing to do with each other. They're generated by different systems at different times. But when a score_update arrives from your Socket.IO backend with a playerId, you need to find the corresponding Mirror NetworkIdentity to apply the effect. And when a Mirror player spawns, you need to register which playerId they belong to so future backend events can reach them.

GameIdentityRegistry is the pattern that solves this.

The Pattern

A static lookup table. Two dictionaries. One clear API.

public static class GameIdentityRegistry
{
    private static readonly Dictionary<uint, string> _netIdToPlayerId = new();
    private static readonly Dictionary<string, uint> _playerIdToNetId = new();

    public static void Register(uint netId, string playerId)
    {
        _netIdToPlayerId[netId] = playerId;
        _playerIdToNetId[playerId] = netId;
    }

    public static NetworkIdentity GetNetworkObject(string playerId)
    {
        if (!_playerIdToNetId.TryGetValue(playerId, out uint netId))
            return null;

        // Check server first, then client
        if (NetworkServer.spawned.TryGetValue(netId, out var identity))
            return identity;
        if (NetworkClient.spawned.TryGetValue(netId, out identity))
            return identity;

        return null;
    }

    public static string GetPlayerId(uint netId)
    {
        return _netIdToPlayerId.TryGetValue(netId, out string playerId)
            ? playerId : null;
    }

    public static void Clear()
    {
        _netIdToPlayerId.Clear();
        _playerIdToNetId.Clear();
    }
}

GetNetworkObject checks NetworkServer.spawned before NetworkClient.spawned — this ensures it works correctly in all Mirror roles: dedicated server, host, and client.

Registration — When and Where

Registration happens in PlayerIdentityBridge, a NetworkBehaviour attached to the Mirror player prefab.

The registration must happen on all instances — server/host and all clients — because GetNetworkObject might be called on any of them when a backend event arrives.

public class PlayerIdentityBridge : NetworkBehaviour
{
    public override void OnStartLocalPlayer()
    {
        var store = FindObjectOfType<LobbyStateStore>();
        CmdRegisterIdentity(store.LocalPlayerId);
    }

    [Command]
    private void CmdRegisterIdentity(string playerId)
    {
        // Register on server/host
        GameIdentityRegistry.Register(netIdentity.netId, playerId);
        // Propagate to all clients
        RpcRegisterIdentity(netIdentity.netId, playerId);
    }

    [ClientRpc]
    private void RpcRegisterIdentity(uint netId, string playerId)
    {
        GameIdentityRegistry.Register(netId, playerId);
    }
}

The flow: local player spawns → OnStartLocalPlayer fires → CmdRegisterIdentity runs on the server → RpcRegisterIdentity propagates to all clients. Every instance now has the mapping.

Usage — Routing Backend Events

When a Socket.IO event arrives with a playerId, resolve it to a Mirror object and apply the effect:

// In GameEventBridge.Subscribe()
game.On("score_update", (string json) =>
{
    var obj = JObject.Parse(json);
    string playerId = obj["playerId"]?.ToString();
    int score = obj.Value<int>("score");

    var identity = GameIdentityRegistry.GetNetworkObject(playerId);
    if (identity == null) return; // player may have left

    identity.GetComponent<PlayerScore>()?.SetScore(score);
});

game.On("player_killed", (string json) =>
{
    var obj = JObject.Parse(json);
    string victimId = obj["victimId"]?.ToString();

    var identity = GameIdentityRegistry.GetNetworkObject(victimId);
    if (identity == null) return;

    identity.GetComponent<PlayerHealth>()?.Die();
});

The null check on GetNetworkObject is important — a player may have disconnected between when the server sent the event and when it arrived. Always guard.

Cleanup — When and Where

Clear the registry in exactly two places:

// 1. On ReturnToLobby — match ended normally
public void ReturnToLobby()
{
    // ... Mirror shutdown ...
    GameIdentityRegistry.Clear();
    // ... LeaveRoom ...
}

// 2. On Socket.IO disconnect — unexpected disconnection
store.OnDisconnected += () => GameIdentityRegistry.Clear();

Missing either case leaves stale mappings. The next match starts with entries from the previous one, GetNetworkObject returns wrong objects, and events apply to destroyed players. Subtle, intermittent, hard to reproduce.

Why Static?

A static class means no singleton MonoBehaviour, no inspector wiring, no FindObjectOfType. Any component anywhere — GameEventBridge, PlayerIdentityBridge, a HUD script — can call GameIdentityRegistry.Register() or GameIdentityRegistry.GetNetworkObject() without a reference.

This is safe because the registry's lifecycle is explicitly managed: Register() populates it, Clear() resets it. There's no implicit state — you always know exactly what's in it based on what's been registered since the last Clear().

The Broader Pattern

GameIdentityRegistry is a specific instance of a general pattern: an identity bridge between two systems that use incompatible ID schemes.

The same pattern applies anywhere two systems need to reference the same logical entity by different identifiers:

• Mirror netId ↔ Steam CSteamID
• Mirror netId ↔ Photon ActorNumber
• Mirror netId ↔ any backend player ID

The implementation is always the same: two dictionaries, a Register() call on spawn, a lookup on event receipt, a Clear() on session end.

The Full Context

This pattern is part of the Mirror Integration sample in socketio-unity — an open-source Socket.IO v4 client for Unity with full WebGL support.

Install via Package Manager → Add package from git URL:

https://github.com/Magithar/socketio-unity.git?path=/package

Then import via Package Manager → Samples → "Mirror Integration" to see the full working implementation.

MIT licensed. Zero paid dependencies.

Have you needed to bridge IDs between two networking systems before? What was your approach?