Forem: Magithar Sridhar

10 Common Unity Rendering Issues (And How to Fix Them Like a Pro)

Magithar Sridhar — Fri, 24 Apr 2026 18:07:02 +0000

If you spend enough time building in Unity, you start to see the same visual bugs over and over again. Weird shadows, flickering textures, scenes that look washed out for no apparent reason — we've all been there.

When you're trying to ship a game, spending hours debugging a shadow artifact is the last thing you want to do.

Over time I've built up a mental cheat sheet for diagnosing these issues quickly. Here are the 10 most common ones, what causes them, and the fastest way to fix each.

1. Shadow Artifacts (Stripes or "Acne")

The cause: Shadow bias or precision issues. The object is casting a shadow on itself.

The fix: Increase the Shadow Bias and Normal Bias on your light source.

If you push the bias too high, the shadow will detach from the object (known as "Peter Panning"). Dial it back just enough until the acne disappears.

2. Jagged or Pixelated Shadows

The cause: Low shadow resolution.

The fix: Go to Quality Settings and increase Shadow Resolution. If you're using a Directional Light, tweaking Shadow Cascades can dramatically improve quality near the camera.

3. Light Bleeding Through Walls

The cause: Light leaking — usually caused by thin meshes or bias settings that are too high.

The fix: Check shadow bias and normal bias first. If those are fine, ensure your meshes have actual thickness. Single-sided planes are notorious for light leaks.

4. Objects Look Too Dark or Flat

The cause: Missing Global Illumination or an incomplete lighting setup.

The fix: Ensure you have ambient light or skybox lighting active. If you're using static geometry, baking your lighting usually solves this and adds much-needed depth.

5. Overbright or Washed Out Scene

The cause: Exposure or Post-Processing Tonemapping issues.

The fix: Check your Post-Processing Volume — specifically Auto Exposure and Color Grading/Tonemapping. Default auto-exposure can go wild in high-contrast scenes.

6. Flickering Textures (Z-Fighting)

The cause: Depth precision issues where two faces occupy the exact same space.

The fix: Make sure your meshes aren't perfectly overlapping. If they aren't, adjust the Near and Far Clip Planes on your Camera. Moving the Near Clip Plane further away increases depth precision.

7. Blurry Textures at an Angle

The cause: Texture import settings — specifically filtering.

The fix: Select the texture in your Project window and increase the Anisotropic Filtering level. This keeps textures sharp when viewed at oblique angles like roads or floors.

8. Sudden Performance Drops in Complex Scenes

The cause: High overdraw (drawing transparent pixels on top of each other) or too many objects pushing the GPU.

The fix: Implement LODs (Level of Detail), use GPU Instancing for repeated objects, and check your overdraw in the Scene window's draw mode selector.

9. Too Many Draw Calls (CPU Bottleneck)

The cause: Unbatched objects. The CPU is telling the GPU to draw too many individual things.

The fix: Enable Static Batching for non-moving objects. For dynamic objects sharing the same material, ensure GPU Instancing or Dynamic Batching is enabled.

10. Weird Lighting or Dark Patches on Meshes

The cause: Broken or inverted normals on the 3D model.

The fix: Select the model in your Project window, go to Import Settings, and set Normals to Calculate instead of Import. If that doesn't work, recalculate normals in Blender or Maya.

Quick Reference

Symptom	Cause	First thing to check
Shadow stripes / acne	Self-shadowing	Shadow Bias on light
Jagged shadows	Low resolution	Quality Settings → Shadow Resolution
Light through walls	Thin mesh / high bias	Mesh thickness + bias values
Flat / dark objects	Missing GI	Ambient light or baked lighting
Washed out scene	Post-processing	Auto Exposure / Tonemapping
Flickering textures	Z-fighting	Near/Far Clip Planes
Blurry angled textures	Filtering	Anisotropic Filtering level
Performance drops	Overdraw / GPU load	LOD + overdraw view
Too many draw calls	Unbatched objects	Static/Dynamic Batching
Dark patches on mesh	Bad normals	Import Settings → Normals: Calculate

I ran into almost all of these while building out my recent multiplayer projects. Once you learn to recognize the symptoms, fixing them becomes second nature.

What rendering issue trips you up most? Got a bug that's driving you crazy right now? Drop a screenshot in the comments and I'll do my best to help diagnose it.

Currently building a Unity WebGL multiplayer library in public — socketio-unity. Follow along to see more of the technical hurdles I run into.

How to Integrate Mirror and SocketIO in Unity — A Hybrid Multiplayer Architecture

Magithar Sridhar — Thu, 23 Apr 2026 00:34:57 +0000

If you've built multiplayer in Unity, you've probably hit this question at some point:

"Do I use Mirror, or do I use a backend with Socket.IO?"

The answer most tutorials give you is pick one. But they're solving different problems — and using both is not only possible, it's the right architecture for most production multiplayer games.

This guide covers exactly how to integrate socketio-unity with Mirror — what each system owns, where the boundary is, and how to implement the integration without the two systems bleeding into each other.

The Core Principle: Two Systems, Two Jobs

Socket.IO is a WebSocket client. It connects your game to a Node.js backend and handles everything that requires a server to broker: matchmaking, lobbies, session identity, authoritative scores, reconnection recovery. The backend is the source of truth. Socket.IO is the pipe.

Mirror is an in-scene networking stack. It synchronises transforms, physics, and animation state between players at frame rate. It has no concept of a backend server and cannot validate gameplay events.

The key insight: Mirror never validates — it only synchronises. Socket.IO never touches transforms — it only brokers.

Socket.IO (Node.js Backend)          Mirror (In-Scene)
─────────────────────────────        ──────────────────
Matchmaking, lobbies, session ──►    StartClient() → server
Scores, kills, round state           NetworkTransform, Rigidbody
Reconnect recovery, host ID          NetworkBehaviour lifecycle

Decision Table: What Goes Where

Concern	Socket.IO	Mirror
Matchmaking / lobby rooms	✅	—
Session identity across reconnects	✅	—
Player transform / position	—	✅
Rigidbody / physics sync	—	✅
Animation state	—	✅
Scores, kill feed, round state	✅	—
Host migration	✅	—
Reconnect recovery	✅	—
Anti-cheat / server validation	✅	—
WebGL browser support	✅	✅ (via SimpleWebTransport)

When you're unsure which system owns something, ask: does this need a server to broker it, or does it need low-latency peer sync? The answer tells you where it goes.

Installation

socketio-unity (v1.4.0+):

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

NativeWebSocket (required dependency):

https://github.com/endel/NativeWebSocket.git#upm

Mirror — install via Package Manager or .unitypackage from the Mirror repo.

Architecture

The session has four distinct phases. Understanding the phase boundaries is more important than any individual line of code.

Session Timeline

Phase 1 — Lobby (Socket.IO only)

Players connect to the /lobby namespace, create or join rooms, exchange session credentials. Mirror is not active at all.

Phase 2 — Match Start (handoff)

The host emits start_match. The backend broadcasts match_started to all room members. This single event is the handoff point — it triggers MirrorGameOrchestrator, which starts Mirror.

Phase 3 — In-Game (both layers active)

Mirror syncs positions via NetworkTransform every frame. Socket.IO delivers authoritative backend events (score_update, player_killed) via the /game namespace. The two systems run in parallel, never touching each other's concerns.

Phase 4 — Teardown (mandatory order)

// Step 1 — Mirror first
if (NetworkServer.active) mirrorNetworkManager.StopHost();
else mirrorNetworkManager.StopClient();

// Step 2 — Clean /game namespace handlers
gameEventBridge.Cleanup();

// Step 3 — Clear netId ↔ playerId mappings
GameIdentityRegistry.Clear();

// Step 4 — Signal intentional leave
lobbyNetworkManager.LeaveRoom();

Reversing steps 1 and 4 is the most common mistake. If you call LeaveRoom() (which closes the socket) before StopHost(), Mirror tries to send disconnect packets over a closed transport. Silent failure, maddening to debug.

The Bridge: GameIdentityRegistry

Mirror speaks in netId (uint). Socket.IO speaks in playerId (string). They need a translation layer.

GameIdentityRegistry is a static lookup table that maps between the two:

// Register on Mirror player spawn
GameIdentityRegistry.Register(netId, playerId);

// Resolve when a Socket.IO event arrives
var identity = GameIdentityRegistry.GetNetworkObject(playerId);
if (identity != null)
{
    // apply event to Mirror object
}

// Clear on ReturnToLobby
GameIdentityRegistry.Clear();

GetNetworkObject checks NetworkServer.spawned first, then NetworkClient.spawned, so it works correctly in all Mirror roles — host, server, or client.

Call Clear() in two places: ReturnToLobby() and store.OnDisconnected. Stale mappings after a disconnect cause events to fire against destroyed objects.

GameEventBridge

GameEventBridge subscribes to /game namespace events and routes them to Mirror objects via GameIdentityRegistry:

public class GameEventBridge : MonoBehaviour
{
    private Action<string> _scoreHandler;
    private Action<string> _killHandler;

    public void Subscribe()
    {
        var game = lobbyNetworkManager.Socket.Of("/game");

        _scoreHandler = (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)
                identity.GetComponent<PlayerScore>()?.SetScore(score);
        };

        _killHandler = (string json) =>
        {
            var obj = JObject.Parse(json);
            string victimId = obj["victimId"]?.ToString();

            var identity = GameIdentityRegistry.GetNetworkObject(victimId);
            if (identity != null)
                identity.GetComponent<PlayerHealth>()?.Die();
        };

        game.On("score_update", _scoreHandler);
        game.On("player_killed", _killHandler);
    }

    public void Cleanup()
    {
        var game = lobbyNetworkManager.Socket.Of("/game");
        game.Off("score_update", _scoreHandler);
        game.Off("player_killed", _killHandler);
    }

    void OnDestroy() => Cleanup();
}

Critical: never call Subscribe() in Start(). The socket may not be initialized yet. Call it from MirrorGameOrchestrator.HandleMatchStarted(), which is guaranteed to run after the socket is fully connected.

Always cache handler references and call Off() in Cleanup(). The event registry holds delegate references — failing to unsubscribe causes callbacks to fire against destroyed MonoBehaviours.

MirrorGameOrchestrator

MirrorGameOrchestrator listens for match_started and coordinates the startup sequence:

public class MirrorGameOrchestrator : MonoBehaviour
{
    [SerializeField] private LobbyStateStore store;
    [SerializeField] private LobbyNetworkManager lobbyNetworkManager;
    [SerializeField] private NetworkManager mirrorNetworkManager;
    [SerializeField] private GameEventBridge gameEventBridge;
    [SerializeField] private ServerMode serverMode;
    [SerializeField] private GameObject lobbyLayer;
    [SerializeField] private GameObject gameLayer;

    private bool _inGame;

    void Start() => store.OnMatchStarted += HandleMatchStarted;

    private void HandleMatchStarted(string sceneName, string hostAddress,
                                     int? kcpPort, int? wsPort)
    {
        if (_inGame) return; // dual guard against duplicate events
        if (NetworkClient.active || NetworkServer.active) return;
        _inGame = true;

        gameEventBridge.Subscribe(); // must happen before StartHost/Client

        lobbyLayer.SetActive(false);
        gameLayer.SetActive(true);

        switch (serverMode)
        {
            case ServerMode.PeerToPeer:
                // Host starts Mirror, others connect to host's LAN IP
                if (store.IsHost)
                    mirrorNetworkManager.StartHost();
                else
                    mirrorNetworkManager.networkAddress = hostAddress;
                    mirrorNetworkManager.StartClient();
                break;

            case ServerMode.DedicatedKCP:
                // All clients connect to dedicated server
                SetKcpPort(kcpPort);
                mirrorNetworkManager.networkAddress = hostAddress;
                mirrorNetworkManager.StartClient();
                break;

            case ServerMode.DedicatedWebSocket:
                SetWsPort(wsPort);
                mirrorNetworkManager.networkAddress = hostAddress;
                mirrorNetworkManager.StartClient();
                break;
        }
    }

    public void ReturnToLobby()
    {
        if (NetworkServer.active) mirrorNetworkManager.StopHost();
        else mirrorNetworkManager.StopClient();

        gameEventBridge.Cleanup();
        GameIdentityRegistry.Clear();
        lobbyNetworkManager.LeaveRoom();

        gameLayer.SetActive(false);
        lobbyLayer.SetActive(true);
        _inGame = false;
    }
}

The _inGame flag plus the Mirror state check is a dual guard against duplicate match_started events — the server can broadcast twice if a reconnect happens mid-handshake.

GameLayer must be inactive at scene start. If it's active when Play begins, NetworkManager.Awake() runs before the orchestrator can deactivate it, initialising Mirror prematurely.

ServerMode

MirrorGameOrchestrator exposes a ServerMode enum as an inspector dropdown. Switch between modes without changing code:

Mode	Who hosts Mirror	Use case
`PeerToPeer`	Room creator runs `StartHost()`, others connect to LAN IP	Local / LAN testing
`DedicatedKCP`	All clients connect to `hostAddress:kcpPort`	Dedicated server, native builds (UDP)
`DedicatedWebSocket`	All clients connect to `hostAddress:wsPort`	Dedicated server, WebGL builds

For dedicated server mode, set MIRROR_SERVER_ADDRESS, MIRROR_KCP_PORT, and MIRROR_WS_PORT as environment variables on your lobby server. The server injects them into every match_started broadcast automatically.

PlayerIdentityBridge

PlayerIdentityBridge runs on the Mirror player prefab and registers the netId ↔ playerId mapping when the player spawns:

public class PlayerIdentityBridge : NetworkBehaviour
{
    [SyncVar(hook = nameof(OnDisplayNameChanged))]
    private string _displayName;

    [SerializeField] private TMP_Text nameLabel;

    public override void OnStartLocalPlayer()
    {
        var store = FindObjectOfType<LobbyStateStore>();
        CmdRegisterIdentity(store.LocalPlayerId);

        string name = store.CurrentRoom?.players
            .FirstOrDefault(p => p.id == store.LocalPlayerId)?.name
            ?? store.LocalPlayerId;
        CmdSetDisplayName(name);
    }

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

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

    [Command]
    private void CmdSetDisplayName(string name)
    {
        _displayName = name;
        OnDisplayNameChanged("", name); // SyncVar hook doesn't fire on host
    }

    private void OnDisplayNameChanged(string _, string newName)
    {
        if (nameLabel != null) nameLabel.text = newName;
    }
}

Note the manual hook call in CmdSetDisplayName — Mirror SyncVar hooks do not fire on the host when the value is set on the server. This is a common gotcha.

Common Pitfalls

Starting Mirror before match_started — always start Mirror inside HandleMatchStarted. Calling StartHost() from a button before the backend confirms creates an orphaned Mirror session.

Using Mirror [Command] for game validation — [Command] goes to the Mirror host, which is a client and can be spoofed. Route all validation through Socket.IO. The backend emits the result; Mirror executes the visual effect.

Double-spawning when migrating from PlayerSync — if your project previously handled player_join via Socket.IO, disable those handlers during the Mirror game phase. Mirror owns all in-scene player lifecycle.

StartClient() failure leaving the player stranded — wire OnClientDisconnect to call ReturnToLobby() so players return to the lobby instead of seeing a blank screen.

The Working Sample

The socketio-unity repo ships a full Mirror Integration sample — lobby → match transition, WASD movement synced via NetworkTransform, lobby display name above each player, graceful shutdown, and a Node.js test server with HTTP endpoints to fire game events from a browser while Unity runs.

Import via Package Manager → Samples → "Mirror Integration".

cd path/to/socketio-unity-mirror-server
npm install
npm run start:mirror

MIT licensed. Zero paid dependencies.

Live WebGL demo: magithar.github.io/socketio-unity/

Have you built a hybrid architecture like this before? What was the hardest part — the boundary between systems, the teardown order, or something else entirely?

Why Your Unity WebGL Multiplayer Breaks on Some Networks

Magithar Sridhar — Fri, 10 Apr 2026 23:05:44 +0000

You test your Unity WebGL multiplayer game. It works perfectly. You share it with a friend — it works. You share it with someone on a corporate network, or a phone hotspot, or after pushing a new build — and it silently fails to connect.

No useful error. No crash. Just... nothing.

This happens because Unity WebGL multiplayer has three distinct failure modes that don't exist in standalone builds: CORS blocks the connection before it opens, WebSocket gets intercepted by a network proxy, and browser cache serves your old build to players days after you deployed a fix.

Here's how to diagnose and fix all three.

1. CORS — the most common first failure

What it is

CORS (Cross-Origin Resource Sharing) is a browser security rule. When your WebGL game at https://yoursite.com tries to connect to https://api.example.com, the browser first sends a preflight OPTIONS request asking "are you allowed to talk to me?" Your Socket.IO server must answer yes.

If it does not, the browser blocks the WebSocket upgrade before it even begins.

What you see

In the browser console (F12 → Console):

Access to fetch at 'https://api.example.com/socket.io/?EIO=4...'
from origin 'https://yoursite.com' has been blocked by CORS policy:
No 'Access-Control-Allow-Origin' header is present

Or in the Network tab: the /socket.io/ request returns status 0 or the WebSocket connection is refused before opening.

Why WebGL is different from desktop

A Unity desktop or mobile build connects as a native TCP socket — no browser, no CORS check. WebGL runs inside the browser, so every connection goes through the browser's security model. The same server that works for your standalone build may refuse WebGL completely.

The fix

On your Node.js Socket.IO server, pass a cors option when creating the server:

import { Server } from "socket.io";
import { createServer } from "http";

const httpServer = createServer();

const io = new Server(httpServer, {
    cors: {
        origin: "https://yoursite.com",   // exact origin, or "*" for open access
        methods: ["GET", "POST"]
    }
});

For local development you often need to allow localhost and your production domain together:

cors: {
    origin: ["http://localhost:8080", "https://yoursite.com"],
    methods: ["GET", "POST"]
}

origin: "*" works but removes all cross-origin protection. Fine for a public demo, not for a game with auth tokens.

Verifying it worked

After fixing the server, check the Network tab in DevTools. The /socket.io/ request should return 200 with these response headers:

Access-Control-Allow-Origin: https://yoursite.com
Access-Control-Allow-Methods: GET,POST

2. WebSocket blocking

What it is

Some networks actively block WebSocket connections. This includes:

Corporate firewalls — WebSocket upgrade requests look unusual; many enterprise proxies strip the Upgrade: websocket header
Carrier-grade NAT and mobile networks — Some mobile carriers terminate WebSocket connections after 30–60 seconds of inactivity
Transparent HTTP proxies — Common in schools, hotels, and public Wi-Fi. These intercept HTTP traffic and cannot forward a WebSocket upgrade
Strict CSP headers — If your hosting adds a Content-Security-Policy header that does not include connect-src wss://your-server.com, the browser blocks the connection

What you see

The connection opens briefly, then closes, often with:

[SocketIO:Transport] Transport error: WebSocket is closed before connection is established

Or the socket connects on the first try but drops every 30–60 seconds on mobile.

The browser console may show:

WebSocket connection to 'wss://...' failed: Error during WebSocket handshake:
Unexpected response code: 200

That 200 instead of 101 means a proxy intercepted and replied instead of letting the WebSocket upgrade through.

Mixed content: the silent variant

If your game page is served over https:// but your Socket.IO server URL starts with ws:// (not wss://), the browser blocks it as mixed content — no error dialog, just a silent drop.

In Unity, your server URL must match the page protocol:

// Page is https:// — use wss://
[SerializeField] private string serverUrl = "wss://your-server.com";

// Page is http:// (local dev) — ws:// is fine
[SerializeField] private string serverUrl = "ws://localhost:3000";

Most hosting platforms (Render, Railway, Fly.io) terminate TLS for you, so your Node.js server can listen on plain HTTP while clients connect over wss://. The TLS layer is handled at the edge.

Polling fallback

Socket.IO supports two transports: WebSocket and HTTP long-polling. Long-polling works through most proxies because it looks like normal HTTPS traffic. Socket.IO will automatically fall back to polling if WebSocket fails during the handshake.

To confirm which transport is active, check the browser Network tab. A persistent WS entry means WebSocket succeeded. Repeated XHR requests to /socket.io/?transport=polling mean it fell back.

CSP fix

If your host adds a Content-Security-Policy header, explicitly allow your Socket.IO server origin:

Content-Security-Policy: connect-src 'self' wss://your-server.com

For GitHub Pages there's no way to set response headers directly — if this is a blocker, move to a host that gives you header control (Netlify, Vercel, and Cloudflare Pages all support _headers files).

3. Browser cache

What it is

When you push a new WebGL build, players on repeat visits may run your old code — the browser served it from disk cache before even asking the server. This is particularly disruptive for multiplayer because the old client sends packets the new server no longer understands.

What you see

A bug you fixed reappears after deployment
Players report "connection looping" while you cannot reproduce it
The Socket.IO version mismatch shows in the handshake: the EIO= query parameter differs between clients

Why Unity WebGL is especially vulnerable

Unity WebGL produces large binary files (.wasm, .data, .framework.js). Browsers aggressively cache large static assets. Unless filenames include a content hash, users will not get the new version until their cache expires — which could be days.

Fixes

Development (testing your own build):

Hard-refresh: Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows/Linux). Use a Private/Incognito window for a fully clean test environment.

Production (your players' browsers):

The correct fix is to version all four asset URLs — the loader, data, wasm, and framework files. The loader is a separate <script> tag, but the data/wasm/framework URLs come from the config object passed to createUnityInstance in index.html. If those filenames are unchanged, the browser will cache them even if the loader itself is fresh.

Version all four in index.html:

<!-- Loader script tag -->
<script src="Build/LiveDemo.loader.js?v=1.3.2"></script>

// createUnityInstance config — version all asset URLs
const config = {
  dataUrl:      "Build/LiveDemo.data.unityweb?v=1.3.2",
  frameworkUrl: "Build/LiveDemo.framework.js.unityweb?v=1.3.2",
  codeUrl:      "Build/LiveDemo.wasm.unityweb?v=1.3.2",
  // ...
};

A CI/CD step can rewrite all four at once using the git commit SHA:

# Linux
GIT_SHA=$(git rev-parse --short HEAD)
sed -i "s|\.unityweb|\.unityweb?v=${GIT_SHA}|g" docs/index.html
sed -i "s|LiveDemo\.loader\.js|LiveDemo.loader.js?v=${GIT_SHA}|" docs/index.html

# macOS requires an empty backup suffix
sed -i "" "s|\.unityweb|\.unityweb?v=${GIT_SHA}|g" docs/index.html
sed -i "" "s|LiveDemo\.loader\.js|LiveDemo.loader.js?v=${GIT_SHA}|" docs/index.html

Also set appropriate cache headers on your static host:

# Aggressive caching for content-hashed assets
Cache-Control: public, max-age=31536000, immutable

# Short cache or no-cache for the loader and index
Cache-Control: no-cache

Diagnostic checklist

When WebGL multiplayer breaks on a specific network or after a deploy, work through this list:

CORS
[ ] Server has cors.origin set to match the page origin
[ ] OPTIONS preflight returns 200 with Access-Control-Allow-Origin

WEBSOCKET BLOCKING
[ ] Page is https:// — server URL is wss://, not ws://
[ ] Network tab shows 101 Switching Protocols, not 200
[ ] No CSP connect-src violation in browser console
[ ] Socket.IO falls back to polling on restrictive networks (check for XHR traffic)

CACHE
[ ] Hard-refresh confirms the bug persists (rules out cache)
[ ] Loader URL has version query string updated after deploy
[ ] No players stuck on old EIO version (check server handshake logs)

Quick reference

Symptom	Most likely cause	First thing to check
Works on your network, fails elsewhere	WebSocket blocked by proxy	Network tab: 101 or 200?
Works standalone, fails in browser	CORS	Console: `Access-Control-Allow-Origin` error
Works on http://, fails on https://	Mixed content	Server URL: `ws://` vs `wss://`
Bug reappears after you fixed it	Browser cache	Hard-refresh, confirm build version
Connects then drops every ~60s	Mobile NAT timeout	Enable ping keepalive; confirm polling fallback
"Connection refused" after new deploy	Old client, new server protocol	Check EIO version in query string

The repo

All of this applies to socketio-unity — the open-source Socket.IO v4 client for Unity this series is built around. MIT licensed, WebGL verified, zero paid dependencies.

Live WebGL demo: magithar.github.io/socketio-unity/

Have you hit a WebGL multiplayer issue that isn't on this list? Drop it in the comments — especially anything weird you've seen on specific mobile carriers or corporate networks.

How to Build a Multiplayer Lobby in Unity with Socket.IO

Magithar Sridhar — Thu, 09 Apr 2026 18:56:08 +0000

Building a multiplayer lobby is where most Unity real-time projects fall apart.

Not the networking part — that's the easy bit. The hard part is everything around it: players joining and leaving mid-session, the host disconnecting and taking the room with them, a player's phone screen locking for 30 seconds and losing their slot forever. Most tutorials stop at "connected". This one doesn't.

This is a complete walkthrough of building a production-ready lobby in Unity using socketio-unity — room creation, join by code, ready states, host migration, and reconnect with a grace window. Every line of code is taken from the real Samples~/Lobby/ sample in the repo, so you can run it locally and pull it apart.

Prerequisites

Unity 2020.1+
Node.js (for the test server)
socketio-unity installed via Window → Package Manager → Add package from git URL:

https://github.com/Magithar/socketio-unity.git

Architecture Overview

Before writing a line of code, the architecture matters. A lobby has three distinct concerns — networking, state, and UI — and mixing them is how you end up with spaghetti that breaks every time the server sends an unexpected event.

The sample uses a clean three-layer split:

LobbyNetworkManager   ← Transport: connects, emits, receives
        ↓ writes
LobbyStateStore       ← State: single source of truth, fires C# events
        ↓ events
LobbyUIController     ← View: subscribes to events, drives UI

The UI never touches the socket directly. The network layer never knows about GameObjects. When something breaks — and in multiplayer, something always breaks — you know exactly which layer to look at.

Step 1 — Connect to the /lobby Namespace

Create a LobbyNetworkManager MonoBehaviour. Use a namespace socket (_root.Of("/lobby")) rather than the root socket — this lets the server scope events cleanly per feature without event name collisions.

private SocketIOClient _root;
private NamespaceSocket _lobby;

private void Start()
{
    _root = new SocketIOClient(TransportFactoryHelper.CreateDefault());
    _root.ReconnectConfig = new ReconnectConfig { autoReconnect = false };

    _lobby = _root.Of("/lobby");
    _root.Connect("http://localhost:3001");
}

Set autoReconnect = false so you control reconnect logic — this is essential for restoring sessions with saved credentials rather than connecting as a fresh player.

Step 2 — Define Your Data Models

The server sends JSON snapshots of the room state. Two things are critical here:

[Preserve] prevents IL2CPP from stripping fields that are only referenced via JSON deserialization — without this, WebGL builds will silently lose data. [JsonProperty] ensures the fields survive minification.

[Serializable, Preserve]
public class RoomState
{
    [Preserve, JsonProperty("roomId")]  public string roomId;
    [Preserve, JsonProperty("hostId")]  public string hostId;
    [Preserve, JsonProperty("version")] public int version;
    [Preserve, JsonProperty("players")] public List<LobbyPlayer> players;
}

[Serializable, Preserve]
public class LobbyPlayer
{
    [Preserve, JsonProperty("id")]     public string id;
    [Preserve, JsonProperty("name")]   public string name;
    [Preserve, JsonProperty("ready")]  public bool ready;
    [Preserve, JsonProperty("status")] public string status; // "connected" | "disconnected"
}

Step 3 — Build the State Store

LobbyStateStore holds authoritative state and exposes C# events. The UI subscribes here — never to the socket directly.

public class LobbyStateStore : MonoBehaviour
{
    public RoomState CurrentRoom   { get; private set; }
    public string LocalPlayerId    { get; private set; }
    public string SessionToken     { get; private set; }
    public bool IsHost             => CurrentRoom != null && CurrentRoom.hostId == LocalPlayerId;

    public event Action OnConnected;
    public event Action OnDisconnected;
    public event Action<RoomState>             OnRoomStateChanged;
    public event Action<LobbyPlayer>           OnPlayerJoined;
    public event Action<string>                OnPlayerLeft;       // playerId
    public event Action<string, string, string> OnPlayerRemoved;   // id, name, reason
    public event Action<SocketError>           OnError;
    public event Action<string>                OnMatchStarted;     // sceneName

    private int _lastRoomVersion;

    public void ApplyRoomState(RoomState newState)
    {
        if (newState == null) return;
        if (newState.version > 0 && newState.version <= _lastRoomVersion) return; // dedupe
        _lastRoomVersion = newState.version;

        DiffAndFirePlayerEvents(CurrentRoom, newState);
        CurrentRoom = newState;
        OnRoomStateChanged?.Invoke(CurrentRoom);
    }

    private void DiffAndFirePlayerEvents(RoomState old, RoomState next)
    {
        if (old == null) return;
        var oldIds = new HashSet<string>(old.players.Select(p => p.id));
        var newIds = new HashSet<string>(next.players.Select(p => p.id));

        foreach (var p in next.players)
            if (!oldIds.Contains(p.id)) OnPlayerJoined?.Invoke(p);
        foreach (var p in old.players)
            if (!newIds.Contains(p.id)) OnPlayerLeft?.Invoke(p.id);
    }

    public void Reset()
    {
        CurrentRoom = null; LocalPlayerId = null; SessionToken = null; _lastRoomVersion = 0;
    }
}

The version check is not optional. During reconnect, the server broadcasts the current room snapshot to the rejoining client — which means the same state can arrive twice. Without the version guard, your UI fires double join/leave events and gets out of sync.

DiffAndFirePlayerEvents lives on LobbyStateStore, called by ApplyRoomState — not on the UI controller. Keep all player diffing logic inside the store.

Step 4 — Wire Up Incoming Events

Subscribe to the four server events in LobbyNetworkManager:

// Server identifies you before room_state arrives
_lobby.On("player_identity", (string json) =>
{
    var obj = JObject.Parse(json);
    store.SetLocalPlayerId(obj.Value<string>("playerId"));
    store.SetSessionToken(obj.Value<string>("sessionToken"));
});

// Authoritative full snapshot
_lobby.On("room_state", (string json) =>
{
    var state = JsonConvert.DeserializeObject<RoomState>(json);
    store.ApplyRoomState(state);
});

// Host started the match
_lobby.On("match_started", (string json) =>
{
    string scene = JObject.Parse(json)["sceneName"]?.ToString();
    store.FireMatchStarted(scene);
});

// Player permanently removed (left or reconnect window expired)
_lobby.On("player_removed", (string json) =>
{
    var obj = JObject.Parse(json);
    store.FirePlayerRemoved(
        obj["playerId"]?.ToString(),
        obj["name"]?.ToString(),
        obj["reason"]?.ToString()
    );
});

Identity ordering matters: the server sends player_identity before the ACK and before room_state. By the time ApplyRoomState fires, IsHost evaluates correctly.

Step 5 — Emit Lobby Actions

Use ACK callbacks for create_room and join_room — they confirm success and return credentials:

Note on ParseAck: The real LobbyNetworkManager.cs handles three response shapes — raw string, JSON array, and JSON object. The snippets below use a simplified version for readability. For production use, copy the full ParseAck implementation directly from the sample to avoid silent failures on the array case.

public void CreateRoom(string playerName)
{
    _lobby.Emit("create_room", new { name = playerName }, ack =>
    {
        var result = ParseAck(ack);
        if (result?.Value<bool>("ok") == true)
        {
            store.SetLocalPlayerId(result.Value<string>("playerId"));
            store.SetSessionToken(result.Value<string>("sessionToken"));
        }
    });
}

public void JoinRoom(string roomId, string playerName)
{
    _lobby.Emit("join_room", new { roomId = roomId.ToUpper(), name = playerName }, ack =>
    {
        var result = ParseAck(ack);
        if (result?.Value<bool>("ok") != true)
            store.FireError(new SocketError(ErrorType.Auth, result?.Value<string>("error")));
    });
}

public void SetReady(bool ready)     => _lobby.Emit("player_ready", new { ready });
public void StartMatch(string scene) => _lobby.Emit("start_match", new { sceneName = scene });

public void LeaveRoom()
{
    _lobby.Emit("leave_room", new { }, _ => store.Reset());
}

Step 6 — Build the Player List UI

Instantiate one prefab row per player. Update without full rebuilds by diffing — recreating all rows on every state update causes flicker and loses UI state:

private readonly Dictionary<string, GameObject> _playerRows = new();

private void HandlePlayerJoined(LobbyPlayer player)
{
    var row = Instantiate(playerRowPrefab, playerListContent);
    _playerRows[player.id] = row;
    UpdateRow(row, player);
}

private void HandlePlayerLeft(string playerId)
{
    if (_playerRows.TryGetValue(playerId, out var row)) Destroy(row);
    _playerRows.Remove(playerId);
}

// Called on every room_state to reconcile the authoritative list
private void RefreshPlayerRows(RoomState state)
{
    var stateIds = new HashSet<string>(state.players.Select(p => p.id));

    foreach (var id in _playerRows.Keys.Except(stateIds).ToList())
    {
        Destroy(_playerRows[id]);
        _playerRows.Remove(id);
    }

    foreach (var player in state.players)
    {
        if (!_playerRows.TryGetValue(player.id, out var row))
            row = _playerRows[player.id] = Instantiate(playerRowPrefab, playerListContent);
        UpdateRow(row, player);
    }
}

private void UpdateRow(GameObject row, LobbyPlayer player)
{
    bool disconnected = player.status == "disconnected";
    var nameText = row.transform.Find("NameText").GetComponent<TextMeshProUGUI>();
    nameText.text = player.id == store.CurrentRoom?.hostId
        ? $"{player.name} [Host]{(disconnected ? " (Reconnecting...)" : "")}"
        : $"{player.name}{(disconnected ? " (Reconnecting...)" : "")}";
    nameText.color = disconnected ? Color.gray : Color.white;

    var icon = row.transform.Find("ReadyIcon").GetComponent<Image>();
    icon.color = disconnected ? Color.yellow : (player.ready ? Color.green : Color.gray);
}

Step 7 — Handle Disconnects and Session Restore

This is where most lobby implementations give up. The server holds a player's slot for 10 seconds after disconnect — their row stays visible with status = "disconnected". On reconnect, send saved credentials to reclaim the slot:

private const string PREF_ROOM_ID       = "Lobby_LastRoomId";
private const string PREF_PLAYER_ID     = "Lobby_PlayerId";
private const string PREF_SESSION_TOKEN = "Lobby_SessionToken";

// Save on every room_state
PlayerPrefs.SetString(PREF_ROOM_ID,       state.roomId);
PlayerPrefs.SetString(PREF_PLAYER_ID,     store.LocalPlayerId);
PlayerPrefs.SetString(PREF_SESSION_TOKEN, store.SessionToken);

// On reconnect — try to restore
private void HandleConnected()
{
    string pid   = PlayerPrefs.GetString(PREF_PLAYER_ID, "");
    string room  = PlayerPrefs.GetString(PREF_ROOM_ID,   "");
    string token = PlayerPrefs.GetString(PREF_SESSION_TOKEN, "");

    if (!string.IsNullOrEmpty(pid) && !string.IsNullOrEmpty(token))
    {
        networkManager.ReconnectSession(pid, room, token);
        StartCoroutine(RejoinTimeout(5f)); // give up after 5 sec
    }
}

public void ReconnectSession(string playerId, string roomId, string sessionToken)
{
    _lobby.Emit("reconnect_player", new { playerId, roomId, sessionToken }, ack =>
    {
        var result = ParseAck(ack);
        if (result?.Value<bool>("ok") != true)
        {
            // Room expired — clear credentials and return to lobby selection
            PlayerPrefs.DeleteKey(PREF_ROOM_ID);
            store.FireError(new SocketError(ErrorType.Auth, result?.Value<string>("error")));
        }
    });
}

The 5-second rejoin timeout is important. If the room expired while the player was disconnected, you don't want to hang on a reconnect attempt forever — clear the stale credentials and return them to the lobby selection screen.

Step 8 — Start the Match

Only the host sees the Start button. On match_started, all clients load the scene:

// In Update() — simpler than event-driven for a toggle
startMatchButton.gameObject.SetActive(store.IsHost);

private void HandleMatchStarted(string sceneName)
{
    if (!string.IsNullOrEmpty(sceneName))
        SceneManager.LoadScene(sceneName);
}

Scene Setup

Canvas
├── LobbySelectionPanel
│   ├── PlayerNameInput (TMP_InputField)
│   ├── CreateRoomButton
│   ├── JoinRoomCodeInput (TMP_InputField)
│   └── JoinRoomButton
├── RoomPanel
│   ├── RoomCodeText (TextMeshProUGUI)
│   ├── CopyRoomCodeButton
│   ├── LeaveRoomButton
│   ├── ReadyButton
│   ├── StartMatchButton        ← toggled by IsHost
│   ├── PlayerList / Content    ← Vertical Layout Group
│   └── ReconnectPanel (overlay)
└── ConnectionStatusText

Assign LobbyNetworkManager and LobbyStateStore to LobbyUIController in the Inspector. Both should be on a DontDestroyOnLoad GameObject if you carry them across scenes.

Key Patterns

Pattern	Why
`room_state.version` check	Ignores duplicate snapshots during reconnect
`player_identity` before ACK	Ensures `IsHost` is correct by the first `room_state`
`_joinInFlight` guard	Prevents double-emit during reconnect sequence
`PlayerPrefs` session storage	Survives app backgrounding, not just network blips
5-second rejoin timeout	Clears stale credentials if the room already expired

Running the Demo

The Samples~/Lobby/ sample includes a full working server:

cd TestServer~
npm install
npm run start:lobby   # or: npm run dev:lobby (auto-restart via nodemon)

The server lives at TestServer~/lobby-server.js. The package.json at TestServer~/package.json already declares express and socket.io as dependencies — no manual installs needed.

Then open the Unity scene and press Play. The sample is the fastest way to see all of this in action before adapting it to your own project.

The Repo

github.com/Magithar/socketio-unity

MIT licensed. Socket.IO v4 only. WebGL verified. Zero paid dependencies.

What's the hardest part of multiplayer lobbies you've had to solve? Host migration, latency compensation, or something else entirely? Drop it in the comments.

How Unity WebGL Talks to a WebSocket Server (The Hard Way)

Magithar Sridhar — Tue, 07 Apr 2026 16:15:29 +0000

When I built socketio-unity, the hardest part wasn't the Socket.IO protocol. It wasn't binary packet assembly or reconnect logic.

It was making WebGL work.

Not "works on my machine" works. Production-verified, binary-safe, multi-socket, reconnect-safe works.

This is the full technical writeup of how the WebGL bridge is built — every design decision, every edge case, and every gotcha that will silently destroy you in production if you miss it.

Why WebGL Needs a Bridge at All

Desktop Unity runs on the .NET runtime — you call System.Net.WebSockets directly and it just works. WebGL is different. Unity compiles your C# to WebAssembly via IL2CPP, which means your code runs inside a browser sandbox with no access to:

No raw sockets from C#
No background threads
No System.Net anything

Every WebSocket operation has to go through the browser's native WebSocket API. And the only way to reach browser APIs from C# in a WebGL build is through a .jslib — a JavaScript file Unity compiles into the final build and exposes to your C# code via DllImport("__Internal").

So instead of calling System.Net.WebSockets directly, you call JavaScript. JavaScript manages the actual socket and fires callbacks back into C# via Unity's SendMessage. That's the bridge.

The Dual-Transport Architecture

The library uses one interface for both platforms:

public interface ITransport
{
    void Connect(string url);
    void SendText(string data);
    void SendBinary(byte[] data);
    void Dispatch();
    void Close();
}

At compile time, a preprocessor guard selects the right implementation:

#if UNITY_WEBGL && !UNITY_EDITOR
    transport = new WebGLWebSocketTransport();
#else
    transport = new NativeWebSocketTransport();
#endif

The !UNITY_EDITOR is not optional. Without it, the Editor tries to compile DllImport("__Internal") which has no backing implementation there — and fails silently in ways that take a long time to diagnose.

Everything above the transport layer — EngineIO, SocketIO, namespaces, ACKs, reconnect — is completely platform-agnostic. It never knows which transport it's talking to.

Files Involved

File	Role
`WebGLWebSocketTransport.cs`	C# side — calls JS functions via `DllImport`
`WebGLSocketBridge.cs`	MonoBehaviour singleton — routes JS callbacks to the right transport
`SocketIOWebGL.jslib`	JavaScript — manages browser `WebSocket` objects
`ITransport.cs`	Platform-agnostic interface
`link.xml`	IL2CPP stripping protection

Socket ID Routing

This is the first non-obvious problem.

The bridge is a singleton — one WebGLSocketBridge MonoBehaviour for the entire application. But a single app can have multiple transports open simultaneously (the root namespace plus several custom namespaces, for example).

When JavaScript fires a callback, how do you know which C# transport it belongs to?

Every WebGLWebSocketTransport generates a GUID on construction. This ID is passed to JavaScript when creating the socket, and prefixed to every callback payload:

JS → C#:  "a1b2c3d4-...:2[\"chat\",\"hello\"]"
            ^^^^^^^^^^^^^^ socketId   ^^^^^^^^^ packet

WebGLSocketBridge maintains five Dictionary<string, Action> maps — open, close, text, binary, error — keyed by socket ID. When a transport connects, it calls Register(). When it closes, it calls Unregister(). The bridge parses the prefix and dispatches to the right handler. No GUID, no routing, no callback collision.

There's also a fallback: both text and binary parsers fall back to _lastActiveSocketId if the payload doesn't contain a socket ID prefix. This handles legacy jslib versions and transitional deployments without breaking anything.

Message Flow

Outbound (emit)

socket.Emit()
  → EngineIOClient.SendRaw()
  → WebGLWebSocketTransport.SendText() / SendBinary()
  → DllImport → SocketIO_WebSocket_SendText / SendBinary
  → browser WebSocket.send()
  → server

For binary sends, the managed byte array has to be pinned before its pointer is handed to JavaScript — otherwise the GC can move it mid-call:

var handle = GCHandle.Alloc(data, GCHandleType.Pinned);
try
{
    SocketIO_WebSocket_SendBinary(socketId, handle.AddrOfPinnedObject(), data.Length);
}
finally
{
    handle.Free();
}

The finally block is not optional. A leaked GCHandle is a memory leak that accumulates silently over a session.

Inbound (receive)

server → browser WebSocket.onmessage
  → JS allocates WASM heap (_malloc), copies bytes, calls SendMessage
  → WebGLSocketBridge.JSOnText / JSOnBinary
  → parses "socketId:payload" or "socketId,ptr,len"
  → dictionary lookup → fires handler on correct transport
  → EngineIOClient parses Socket.IO packet
  → game On() handler invoked

Binary inbound is the most delicate part of the entire bridge. The flow:

JavaScript receives an ArrayBuffer from the server
JS calls _malloc() to allocate memory on the WASM heap
JS copies the ArrayBuffer bytes into that allocation
JS calls SendMessage with the pointer and length
C# calls Marshal.Copy((IntPtr)ptr, data, 0, len) to pull it into managed memory
JS immediately calls _free() on the allocation

Step 6 has to happen after step 5. If you free before C# has copied, you're reading deallocated memory. If you forget to free at all, you leak WASM heap on every binary message received.

The jslib handles this:

socket.onmessage = function(e) {
    if (e.data instanceof ArrayBuffer) {
        var bytes = new Uint8Array(e.data);
        var ptr = _malloc(bytes.length);
        HEAPU8.set(bytes, ptr);
        SendMessage('WebGLSocketBridge', 'JSOnBinary', socketId + ',' + ptr + ',' + bytes.length);
        _free(ptr);
    }
};

One more thing: binaryType = "arraybuffer" must be set on the socket at creation time. Without it, binary messages arrive as Blob — which cannot be synchronously read inside the callback. This is silent. The message arrives, your handler fires, and the data is just... not there.

var socket = new WebSocket(url);
socket.binaryType = "arraybuffer"; // without this, binary is broken

Dispatch() is a No-Op

On desktop, Dispatch() is called every frame to pump the WebSocket message queue. The native transport needs it — async operations need to be ticked.

On WebGL, Dispatch() does nothing. The browser's event loop drives message delivery. When a message arrives, the browser fires onmessage, which calls SendMessage, which routes directly to the C# handler. There's no queue to pump.

This is one of those things that looks wrong when you first read it but is correct.

Reconnection Safety

Each reconnect cycle:

Closes the old transport — which fires Unregister(), removing its GUID from all five dictionaries
Creates a new transport — which generates a new GUID on construction
Connects, which calls Register() with the new GUID

No stale callback references. No GUID collisions. No events firing on a transport that no longer exists.

IL2CPP Stripping

WebGL builds use IL2CPP with aggressive dead-code elimination. Any type that's only referenced at runtime — via JSON deserialization, reflection, or SendMessage — gets stripped and produces silent failures.

The link.xml in the package preserves the types the bridge depends on:

<linker>
  <assembly fullname="socketio-unity">
    <type fullname="UnityMainThreadDispatcher" preserve="all"/>
    <type fullname="UnityTickDriver" preserve="all"/>
  </assembly>
</linker>

If you're deserializing your own data models from Socket.IO events and they're disappearing in WebGL builds, they need entries here too.

WebGL vs Native at a Glance

Aspect	WebGL	Native
WebSocket API	Browser `WebSocket`	`System.Net.WebSockets`
Thread model	Single (browser event loop)	async/await
`Dispatch()`	No-op	Must call each frame
Binary memory	Manual `_malloc` / `_free`	Automatic GC
Interop	`DllImport("__Internal")`	Direct .NET
Socket ID	GUID per transport	N/A

Production Gotchas

CORS. The Socket.IO server must explicitly allow the page origin. A CORS rejection in WebGL produces no useful error — the socket just fails to connect.

Browser cache. Stale .unityweb assets serve old jslib code after you've updated the bridge. Force-refresh (Cmd+Shift+R) or use Incognito during development. This has caused more confusion than any other single issue.

IL2CPP stripping. Any type only referenced via JSON deserialization needs link.xml preservation. The symptoms are random NullReferenceExceptions in WebGL builds that don't reproduce in the Editor.

binaryType = "arraybuffer". Set it on socket creation in the jslib, always. Without it, binary messages arrive as Blob and are silently unreadable.

The Full Picture

The WebGL bridge in socketio-unity isn't a hack or a workaround. It's a proper interop layer — dual transport with a clean interface, GUID-based routing, pinned memory for outbound binary, malloc/free for inbound binary, and IL2CPP stripping protection.

Most of this complexity is invisible when you're just calling socket.Emit(). That's the point.

If you're building Unity multiplayer with a Socket.IO backend — WebGL included:

Repo: github.com/Magithar/socketio-unity · Live demo: magithar.github.io/socketio-unity/ · MIT licensed. Zero paid dependencies.

If this saved you a few hours of pain, a ⭐ on the repo goes a long way.

How I Built a Socket.IO v4 Client for Unity from Scratch (with WebGL Support)

Magithar Sridhar — Mon, 06 Apr 2026 11:57:40 +0000

Every Unity multiplayer developer hits the same wall.

You've got a Node.js backend running Socket.IO. Your web client connects in three lines. Then you open the Unity docs, search the Asset Store, and spend two hours realising that the Unity side of this equation is... a mess.

That's where I was. And it's why I built socketio-unity.

The State of Socket.IO in Unity (Before This)

When I started, the options were grim:

Paid assets with no source code and no way to fix bugs yourself
Abandoned repos targeting Socket.IO v2 or v3, incompatible with the current protocol
WebGL support that was either broken or missing entirely — and WebGL multiplayer is huge if you want browser-based games

I needed something open-source, Socket.IO v4, and WebGL-verified. It didn't exist, so I built it.

The Architecture (High Level)

Before diving into the hard part, here's the shape of the library:

Socket.IO Server
      ↓
  ITransport  ←── WebSocketTransport (Standalone)
              ←── WebGLWebSocketTransport (Browser)
      ↓
 EngineIOClient  (handshake, heartbeat, RTT)
      ↓
 SocketIOClient  (namespaces, events, ACKs, binary)
      ↓
 SocketIOManager (Unity singleton)

A single WebSocket connection. Namespaces multiplexed over it. Tick-driven — no background threads. Everything dispatched on Unity's main thread.

The public API ends up feeling natural for Unity developers:

var socket = SocketIOManager.Instance.Socket;

socket.OnConnected += () => Debug.Log("Connected!");
socket.On("chat", msg => Debug.Log(msg));

socket.Connect("ws://localhost:3002");
socket.Emit("chat", "Hello from Unity!");

Getting there wasn't straightforward. The hardest part wasn't the protocol parsing, or the reconnect logic, or the binary packet assembly.

It was WebGL.

The WebGL Problem (And How I Solved It)

WebGL builds don't run on the .NET runtime. They compile to WebAssembly, which means your C# code runs in the browser — but it can't touch browser APIs directly. No raw sockets. No threads. No System.Net.

For WebSocket specifically, you have to go through a JavaScript bridge: a .jslib file that Unity compiles into the final build and exposes to your C# code via DllImport.

Here's what that looks like at the boundary:

// C# side — calling into JS
[DllImport("__Internal")]
private static extern void SocketIOConnect(string url);

[DllImport("__Internal")]
private static extern void SocketIOSend(string data);

// SocketIOWebGL.jslib — the JS side
mergeInto(LibraryManager.library, {
  SocketIOConnect: function(urlPtr) {
    var url = UTF8ToString(urlPtr);
    // create WebSocket in browser JS, wire up callbacks
    socket = new WebSocket(url);
    socket.onmessage = function(e) {
      // marshal data back to C#
      SendMessage('SocketIOManager', 'OnWebGLMessage', e.data);
    };
  }
});

Sounds manageable. In practice there were three brutal edge cases.

1. String marshalling across the boundary

Passing strings between C# and JS in Unity WebGL requires manual memory management. You allocate a buffer in the JS heap, write the UTF-8 bytes, pass the pointer to C#. If you get the buffer size wrong, or forget to free it, you get silent corruption or memory leaks that only appear after hundreds of messages.

2. Binary data

Socket.IO supports binary events — you can send byte[] payloads alongside JSON. In WebGL, ArrayBuffer from JS can't be passed directly to C# as a byte array. You have to Base64-encode it in JS, pass it as a string, decode it in C#.

For large payloads (say, 10MB in stress tests) this adds real overhead. But it was the only reliable cross-boundary option.

3. Domain reload safety

Unity's editor reloads the domain (re-initialises all C# state) when you enter Play mode. If your .jslib holds a reference to a WebSocket that no longer has a C# counterpart, you get ghost connections — sockets that are open in JS but invisible to C#, firing events into the void.

The fix was a cleanup hook in OnDisable that explicitly closes the JS-side socket on every domain reload:

void OnDisable()
{
#if UNITY_WEBGL && !UNITY_EDITOR
    SocketIOClose();
#endif
}

Simple when you know. Absolutely maddening to diagnose before you do.

Other Things Worth Knowing

Reconnect with backoff and jitter

Reconnect logic seems easy until you have 500 clients all disconnecting at once and hammering your server simultaneously. Jitter spreads the reconnect attempts across a window:

socket.ReconnectConfig = new ReconnectConfig
{
    initialDelay  = 1f,
    multiplier    = 2f,
    maxDelay      = 30f,
    maxAttempts   = -1,
    jitterPercent = 0.1f,  // ±10% randomness on each delay
};

Everything runs on the main thread

Unity's API is not thread-safe. Any callback that touches a GameObject, Transform, or Debug.Log needs to be on the main thread. The library uses UnityMainThreadDispatcher to queue all event callbacks — so you never have to think about this.

CI on every commit

The test suite covers 38+ protocol edge cases, binary assembler correctness, ACK overflow, reconnect config, and stress tests (1K events, 10MB binary, 100 concurrent ACKs). It runs on Unity 2022.3 LTS via GitHub Actions on every push.

Using It in Your Project

Install via Package Manager → + → Add package from git URL:

https://github.com/Magithar/socketio-unity.git

You'll also need NativeWebSocket:

https://github.com/endel/NativeWebSocket.git#upm

Then create an empty GameObject, attach SocketIOManager, and you're connected.

There are four samples included (Basic Chat, PlayerSync, Lobby, LiveDemo) each with a Node.js test server you can run locally.

What I'd Do Differently

Honestly? Start with the WebGL bridge earlier. I designed the transport abstraction (ITransport) upfront specifically to keep WebGL isolated from the rest of the stack — but I still underestimated how much the JS boundary would dictate the architecture around binary data and lifecycle management.

If you're building anything that needs to run in a browser, design for WebGL constraints from day one, not as an afterthought.

The Repo

github.com/Magithar/socketio-unity

Want to see it running in a browser before installing anything?

There's a live WebGL demo — open it in two tabs to watch real-time player sync in action.

MIT licensed. Socket.IO v4 only. WebGL verified. Zero paid dependencies.

If you're building multiplayer in Unity and connecting to a Socket.IO backend — give it a try. Issues and PRs welcome.

If this saved you a few hours of pain, a ⭐ on the repo goes a long way.

Forem: Magithar Sridhar

10 Common Unity Rendering Issues (And How to Fix Them Like a Pro)

1. Shadow Artifacts (Stripes or "Acne")

2. Jagged or Pixelated Shadows

3. Light Bleeding Through Walls

4. Objects Look Too Dark or Flat

5. Overbright or Washed Out Scene

6. Flickering Textures (Z-Fighting)

7. Blurry Textures at an Angle

8. Sudden Performance Drops in Complex Scenes

9. Too Many Draw Calls (CPU Bottleneck)

10. Weird Lighting or Dark Patches on Meshes

Quick Reference

How to Integrate Mirror and SocketIO in Unity — A Hybrid Multiplayer Architecture

The Core Principle: Two Systems, Two Jobs

Decision Table: What Goes Where

Installation

Architecture

Session Timeline

The Bridge: GameIdentityRegistry

GameEventBridge

MirrorGameOrchestrator

ServerMode

PlayerIdentityBridge

Common Pitfalls

The Working Sample

Why Your Unity WebGL Multiplayer Breaks on Some Networks

1. CORS — the most common first failure

What it is

What you see

Why WebGL is different from desktop

The fix

Verifying it worked

2. WebSocket blocking

What it is

What you see

Mixed content: the silent variant

Polling fallback

CSP fix

3. Browser cache

What it is

What you see

Why Unity WebGL is especially vulnerable

Fixes

Diagnostic checklist

Quick reference

The repo

See also

How to Build a Multiplayer Lobby in Unity with Socket.IO

Prerequisites

Architecture Overview

Step 1 — Connect to the /lobby Namespace

Step 2 — Define Your Data Models

Step 3 — Build the State Store

Step 4 — Wire Up Incoming Events

Step 5 — Emit Lobby Actions

Step 6 — Build the Player List UI

Step 7 — Handle Disconnects and Session Restore

Step 8 — Start the Match

Scene Setup

Key Patterns

Running the Demo

The Repo

How Unity WebGL Talks to a WebSocket Server (The Hard Way)

Why WebGL Needs a Bridge at All

The Dual-Transport Architecture

Files Involved

Socket ID Routing

Message Flow

Outbound (emit)

Inbound (receive)

Dispatch() is a No-Op

Reconnection Safety

IL2CPP Stripping

WebGL vs Native at a Glance

Production Gotchas

The Full Picture

How I Built a Socket.IO v4 Client for Unity from Scratch (with WebGL Support)

The State of Socket.IO in Unity (Before This)

The Architecture (High Level)