DEV Community: Magithar Sridhar

The Bug Was in My Own Instructions, Not My Code

Magithar Sridhar — Tue, 14 Jul 2026 16:48:28 +0000

In my last article, a reader's comment exposed a hole in SKILLmama's design, and I shipped Phase 1.5 to fix it. This time, nobody had to point anything out to me. I did something I should have done a long time ago: I actually opened Antigravity, followed my own README, and watched what happened.

It didn't work.

The Recording

SKILLmama supports four agents — Claude Code, Claude.ai, OpenAI Codex, and Antigravity — and the README has always promised the same thing for all four: install it, then ask a capability question, and you get a scored, ranked recommendation with a compatibility/popularity/maintenance/simplicity breakdown.

I had never actually verified that claim for Antigravity. So I opened it, typed:

find me the best vector database for a Python project

And got back a plain, generic answer. No stack scan. No constraint question. No scoring table. Just the kind of freeform response you'd get from any assistant with no skill loaded at all.

SKILLmama wasn't running. It wasn't even trying.

The Wrong Guesses

My first assumption was reasonable: the npx skills add CLI I'd been telling people to use must be installing to a path Antigravity doesn't check. I went and read the CLI's own source (vercel-labs/skills) to find the real path. Found what looked like the answer. Copied the skill file there by hand. Restarted Antigravity. Tested again.

Still nothing. Same generic answer.

Second guess. Maybe I had the wrong directory entirely. I tried another path that seemed plausible from the CLI's agent config. Restarted again. Tested again.

Still nothing.

Two wrong guesses in a row are usually a sign you're debugging the wrong layer. I was reverse-engineering a tool that manages the skill, when I should have been reading what the agent itself actually documents about where it looks.

The Real Answer Was in the Docs I Hadn't Read

antigravity.google/docs/skills — the actual, official documentation for how Antigravity discovers skills. I hadn't opened it once before this.

It states, plainly, two locations:

Project scope: <workspace-root>/.agents/skills/<skill-folder>/
Global scope:  ~/.gemini/config/skills/<skill-folder>/

Neither of my two guesses matched. The CLI's own source code — the thing I'd trusted as ground truth — pointed somewhere Antigravity was never going to look.

I copied the skill to the real path, restarted Antigravity one more time, and asked it directly: "Which skills are installed?"

SKILLmama — AI-Native Capability Discovery Engine

There it was, listed under Global & Built-in Skills, sitting right next to Antigravity's own native commands. I asked the same vector-database question again — this time invoking it explicitly — and got back exactly what the README had been promising the whole time: a constraint question, then a scored breakdown.

It worked. It had just never worked the way I'd been telling people to install it.

Closing the Loop

Once I had a real repro, I checked whether anyone else had already run into this — and found an open issue on vercel-labs/skills asking for the exact fix Antigravity actually needs. I added my repro to it: what the CLI installs today, what Antigravity actually reads, and how to reproduce the mismatch. Not my repo to fix, but worth leaving evidence for whoever does.

The README now leads with the manual install to the correct path — confirmed, not assumed — and only mentions the CLI as a secondary option with an explicit warning about where it currently goes wrong.

Bonus: While I Was In There

Chasing down the Antigravity bug surfaced two more things worth fixing in the same pass:

Scoring got more honest. The Compatibility score used to be inferred purely from your detected stack. Now, before scoring, SKILLmama checks your actual environment — does the required env var exist in .env.example? Is the CLI on your PATH? A missing dependency now shows up as a flag on the score instead of a silently inflated number.

The four adapters had quietly drifted apart. codex/AGENTS.md and antigravity/PROMPT.md still carried leftover wording from an earlier two-stage architecture that had since been dropped — meaning the instructions Codex and Antigravity were actually running had subtly diverged from the canonical pipeline in skillmama/SKILL.md. Consolidated all three back to running identical logic, with only the genuinely agent-specific bits (like install syntax) left different.

What Changed

All of this is live in v1.4.3. For Antigravity specifically:

mkdir -p ~/.gemini/config/skills/skillmama
curl -sL https://raw.githubusercontent.com/Magithar/SKILLmama/main/skillmama/SKILL.md \
  -o ~/.gemini/config/skills/skillmama/SKILL.md

Restart Antigravity, then invoke it explicitly: SKILLmama find me a vector database for this project.

github.com/Magithar/SKILLmama — Apache 2.0.

The lesson wasn't really about Antigravity. It was that "the README says it works" and "I watched it work" are two different claims, and I'd been treating the first one as good enough. It isn't. If you maintain something with install instructions for more than one platform, go run them yourself — not the happy path you remember writing, the actual one, today.

10 Common Unity Networking Issues (and How to Fix Them)

Magithar Sridhar — Mon, 06 Jul 2026 21:21:30 +0000

Multiplayer bugs in Unity rarely look like networking bugs. They look like "the game froze," "the player teleported," or "it worked in the Editor and broke in the WebGL build." By the time you've traced it back to the actual cause, you've usually burned an afternoon.

Here are 10 issues that show up constantly in Unity networking code (WebSocket-based, Socket.IO, or otherwise) with the actual root cause and the fix. A few of these come straight out of real regression tests and commit history in socketio-unity, an MIT-licensed Socket.IO v4 client for Unity. The rest are patterns you'll recognize if you've shipped a multiplayer game.

1. Reconnect wipes your room/namespace state

Symptom: Connection drops for two seconds, comes back, and the player is no longer in their room/lobby/channel, even though the server never removed them.

Cause: A common (bad) reconnect implementation tears down the whole client and rebuilds it from scratch, including the list of channels/namespaces the player had joined. The reconnect "succeeds" at the transport level but silently drops application-level state.

Fix: Reconnect logic should preserve subscriptions across the transport reset and only re-emit join/connect for namespaces the client already had open. If you're rebuilding the socket object on every reconnect attempt, stop. Reconnect the transport, keep the namespace map.

// Wrong: rebuilds everything, loses namespace state
void OnReconnect() => CreateFreshEngine();

// Right: reuses the existing namespace map
void OnReconnect() => ReconnectEngine(); // _namespaces untouched

2. "get_gameObject can only be called from the main thread"

Symptom: Random UnityException thrown from inside a network event handler, but only sometimes, usually right when the server sends something.

Cause: Your WebSocket/network library delivers callbacks on its own I/O thread. Any Unity API call (transform.position =, Instantiate, even some Debug.Log paths) from that thread throws.

Fix: Never touch Unity APIs directly in a network callback. Queue the work and drain the queue from Update() on the main thread.

socket.OnMessage += data => {
    UnityMainThreadDispatcher.Enqueue(() => {
        // Safe: runs on the main thread next Update()
        player.transform.position = ParsePosition(data);
    });
};

This is table stakes for any Unity networking layer. If the library you're using doesn't do this for you automatically, you're going to hit this bug in production, not in testing.

3. `Connect()` hangs with no timeout

Symptom: State sits at Connecting indefinitely. No error, no timeout, no exception. Just silence. Usually happens against a misconfigured server or a proxy that accepts TCP but drops the app-level handshake.

Cause: Most networking code has a timeout for "can't reach the server" (connection refused) but not for "reached the server, and it's just... not responding." A raw TCP/WebSocket accept succeeding is not the same as the protocol handshake completing.

Fix: Add an explicit handshake timeout that's separate from the reconnect backoff, and make sure it only applies to the initial connect. Reconnect attempts should use their own backoff.

config.connectTimeoutMs = 10000; // abort with OnError(Timeout) if no handshake in 10s

Don't ship without a default. Set it to 0 only if you have a specific reason to wait indefinitely.

4. WebGL builds behave nothing like the Editor

Symptom: Everything works in Editor and Standalone. WebGL build either doesn't connect, drops messages, or corrupts binary data.

Cause: WebGL doesn't have real threads or a real socket API. Your networking code has to bridge into browser JavaScript via a .jslib plugin, which means a completely different code path (and completely different failure modes) than every other platform. String/byte marshalling between C# and JS is a common place for subtle bugs, for example framing a socket ID and message body with a delimiter character that can also appear inside the message body.

Fix: Don't assume "works on Desktop" implies "works on WebGL." Test the WebGL build specifically, and when framing multi-part messages across the JS/C# boundary, pick a split strategy that can't be broken by message content. For example, split on the first occurrence of a delimiter that's guaranteed not to appear in the ID (like a GUID), not by a fragile index heuristic.

// Fragile: assumes id length is always under 40 chars
var id = raw.substring(0, 40);

// Robust: split on first colon; GUIDs never contain one
var idx = raw.indexOf(':');
var id = raw.substring(0, idx);
var msg = raw.substring(idx + 1); // safe even if msg itself contains colons

5. IL2CPP stripping deletes types that only exist at runtime

Symptom: A MonoBehaviour or class works perfectly in the Editor, then throws MissingMethodException or silently no-ops in an IL2CPP build, but only in the build, never in Play mode.

Cause: IL2CPP's code stripper removes anything it can't prove is used, based on static analysis of scene/prefab references. If you create a component at runtime via AddComponent<T>() or reflection rather than referencing it in a scene, the stripper doesn't see the reference and deletes it.

Fix: Explicitly preserve runtime-created types in link.xml.

<linker>
  <assembly fullname="YourAssembly">
    <type fullname="YourNamespace.RuntimeCreatedComponent" preserve="all" />
  </assembly>
</linker>

If you add a new MonoBehaviour that's instantiated dynamically (not dragged into a scene), add it to link.xml in the same PR. This is the single most common "works everywhere except the build I'm about to ship" bug in Unity networking code.

6. A malformed binary packet crashes the whole handler pipeline

Symptom: One bad server message and the client stops processing all subsequent binary events, or throws a NullReferenceException that spams every frame.

Cause: Binary protocols (file transfer, voice chat, custom serialization) often use a placeholder/reference scheme for large payloads. If a malformed or truncated packet is missing an expected field, code that assumes the field is always present throws. If that throw happens inside a per-frame processing loop instead of being caught at the boundary, it repeats forever.

Fix: Validate untrusted server input at the parsing boundary, not deep in application logic, and wrap binary assembly in a try/catch that routes to your normal error channel instead of letting the exception propagate.

try {
    var payload = BinaryPacketAssembler.Build(placeholders, buffers);
    Handle(payload);
} catch (Exception e) {
    OnError?.Invoke(new SocketError(ErrorType.Protocol, e.Message));
    // don't rethrow - one bad packet shouldn't kill the pipeline
}

Never assume a server-supplied packet is well-formed. Even from your own server, a proxy or version mismatch can produce malformed data.

7. "Heartbeat timeout" that isn't actually a network problem

Symptom: Client disconnects with a heartbeat/ping timeout error. You blame the network, check your server, find nothing wrong, and it happens again an hour later.

Cause: If your event handlers, once correctly dispatched to the main thread (see #2 for the threading model), do something slow like a big JSON parse, a physics query, or an asset load, they can block the main thread long enough that the ping/pong cycle misses its deadline. The client concludes the connection died when actually the game stalled.

Fix: Before assuming it's a server/network issue, profile your event handlers for anything synchronous and slow. Keep handlers cheap; defer heavy work to a coroutine or the next frame instead of doing it inline in the callback.

8. Namespace/room auth fails silently

Symptom: Client connects to the root namespace fine, but a sub-namespace/room never triggers its connect event and no error appears anywhere obvious.

Cause: Joining an authenticated namespace/channel usually requires passing an auth payload at connect time, not after. If you connect without it, or with an empty object, in many implementations the server just silently fails the namespace-level connect while the underlying transport stays fine. Nothing crashes, so nothing looks wrong.

Fix: Always listen for a connect_error on the namespace itself, and double-check you're passing auth at the point of connection, not as an afterthought:

// Wrong - no auth, silently rejected
socket.Of("/admin");

// Right
socket.Of("/admin", new { token = sessionToken });
socket.Of("/admin").OnConnectError += err => Debug.LogError(err);

9. Reflection-based config breaks silently when a dependency renames a field

Symptom: A dedicated-server or multi-transport setup (for example, switching ports based on platform) works, then silently uses the wrong port after an unrelated dependency update. No compile error, no exception.

Cause: Code that sets configuration via reflection (GetField/GetProperty by string name, because the target type is defined in a third-party package you don't want a hard dependency on) is invisible to the compiler. If the third-party library renames a field from a public field to a property (or vice versa) in an update, your reflection call finds nothing, fails silently, and the fallback/default value gets used instead.

Fix: If you must use reflection for soft dependencies, check both field and property, and log loudly (not silently swallow) when neither is found. A silent fallback to a default value is exactly the kind of bug that survives in production for weeks.

var field = type.GetField("port");
if (field != null) { field.SetValue(transport, port); return; }

var prop = type.GetProperty("port");
if (prop != null) { prop.SetValue(transport, port); return; }

Debug.LogWarning($"Could not find 'port' field or property on {type.Name} - falling back to inspector value");

10. Two reconnect timers running at once

Symptom: After a rough network patch, you see reconnect attempts firing twice as often as configured, or backoff resetting unpredictably.

Cause: If your reconnect controller's Start() isn't idempotent, calling it twice (for example, once from OnDisconnect and once from a manual retry button, or once per re-entrant event) spins up a second timer loop instead of being a no-op.

Fix: Guard Start() explicitly, and don't remove the guard during a refactor just because it looks redundant in the happy path. It's there for the unhappy path.

public void Start() {
    if (_enabled) return; // idempotency guard - do not remove
    _enabled = true;
    ScheduleNextAttempt();
}

The common thread

Almost none of these are "hard" bugs. They're boundary bugs. Main thread vs. network thread. Editor vs. IL2CPP build. Desktop vs. WebGL. Trusted code vs. untrusted server input. Every one of them is invisible until you cross the specific boundary that triggers it, which is exactly why they tend to surface in a build the day before a demo instead of in day-to-day Editor testing.

If you're building Socket.IO-based multiplayer for Unity and would rather not rediscover these the hard way, socketio-unity is an MIT-licensed Socket.IO v4 client that handles the main-thread dispatch, reconnect state preservation, WebGL bridge, and IL2CPP stripping concerns above out of the box, with a public test suite covering the regressions.

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

A Reader Pointed Out My "Ask First" Principle Only Covered Half My Tool — So I Fixed It

Magithar Sridhar — Tue, 30 Jun 2026 22:50:34 +0000

In my last article, I added Flow B to SKILLmama: run /skillmama with no arguments, and it scans your project, finds capability gaps, and asks before it searches. The whole point was to stop the AI from guessing what you need.

Then @alexshev left this comment:

Having the AI ask first is underrated because it changes the contract from answer-generation to ambiguity-reduction. The best agents I have used spend a little time shrinking the unknowns before they touch code.

"Ambiguity-reduction over answer-generation." That's a sharper framing of the idea than I'd come up with myself. But reading it back, I realized the comment had quietly exposed a hole in my own design.

The Hole

SKILLmama has two entry points:

Flow B — /skillmama with no args → scan → ask → search
Flow A — /skillmama find me a job queue → scan → search

Flow B asked first. Flow A didn't.

When you named a capability directly, SKILLmama scanned your project for stack context — and then went straight to searching and ranking. It reduced the ambiguity it could see from your files, but it never reduced the ambiguity it couldn't: budget, license, self-hosted vs. hosted, "must work with what I already run."

So /skillmama find me a job queue on a solo side project would happily return an enterprise-grade, infra-heavy #1 pick — technically the highest score, practically wrong for the person asking. The commenter's principle applied perfectly to Flow B. Flow A was still in answer-generation mode.

The Fix: Phase 1.5

I added one step to Flow A: Confirm Constraints.

Phase 0   — parse the request
Phase 1   — scan the project
Phase 1.5 — if no constraints were stated: ask ONE informed question, then STOP   ← new
Phase 2   — derive search terms
Phase 3   — search
...

The key word is informed. Because Phase 1 already scanned your stack, the question isn't a generic "any constraints?" — it's built from what it just found:

SKILLmama: I see you're on Python / FastAPI / PostgreSQL / Docker / OpenAI.
Before I search — any constraints? (e.g. self-hosted, open-source only,
free tier, must integrate with PostgreSQL). Reply "none" to search with no filters.

Then it stops and waits — same hard stop that makes Flow B collaborative.

The Three Rules That Keep It From Being Annoying

A clarifying question is only good if it doesn't fire when it shouldn't. So Phase 1.5 has guardrails:

1. It only fires when you gave no constraints. If you already said find me an open-source job queue, the constraint is on the table — it skips the question and searches immediately. No nagging.

2. It degrades gracefully. If there are no project files to scan (empty folder, fresh repo), it doesn't print a broken I see you're on [nothing] sentence. It falls back to a generic constraint question instead.

3. It asks once. No re-prompting loops. One question, your answer (or "none"), then it runs.

Why "One Informed Question" Beats "A Form"

I could have made Flow A ask the same three questions Flow B asks. I didn't, on purpose.

Flow B earns three questions because it's doing open-ended discovery — it found a handful of gaps and needs to know which ones matter, what your constraints are, and what it missed. Flow A already knows the capability. The only real unknown left is constraints. Asking more than that would be friction for its own sake.

The contract the commenter described — shrink the unknowns before you touch code — doesn't mean "ask everything." It means ask for the smallest input that most changes the output. For a scored ranking, that input is constraints: a single "must be self-hosted" can reorder the entire top 3.

What Changed

Phase 1.5 is live in v1.4.0 across all four adapters — Claude Code, Claude.ai, OpenAI Codex, and Antigravity. Both entry points now reduce ambiguity before they act; they just ask the right number of questions for how much they already know.

npx skills add Magithar/SKILLmama

github.com/Magithar/SKILLmama — Apache 2.0.

And if you've got a sharp observation about where it still guesses instead of asking — leave a comment. The last one became a release.

I Got Tired of Asking "What Am I Missing?" — So I Made My AI Ask First

Magithar Sridhar — Tue, 30 Jun 2026 20:11:39 +0000

In my first article, I built SKILLmama: an AI skill that finds, scores, and ranks the best library for your exact stack.

In my second article, I added a security gate — because a high score means nothing if the tool is dangerous.

Both of those workflows had the same assumption baked in: you already know what you're looking for.

You type /skillmama find me a job queue for Node.js and it searches, scores, and returns ranked picks. That's great when you have a specific gap in mind.

But most of the time, you don't. You're deep in building something and you haven't stopped to ask: do I have auth? do I have observability? do I have a queue? You find out the hard way — when a feature ships without rate limiting, or when something breaks and there's no error tracking.

So I flipped the workflow. In v1.3, /skillmama with no arguments scans your project first and asks what to find.

The Old Flow vs. The New Flow

Before (Flow A — still exists):

/skillmama find me an auth library for Next.js
    ↓
scan project for stack context
    ↓
search → score → recommend

Now (Flow B — triggered when no capability is given):

/skillmama
    ↓
deep scan: reads package files, config, source structure
    ↓
gap analysis: what's missing for this type of project?
    ↓
ask 3 questions — STOP and wait for your answer
    ↓
you pick a gap → search → score → recommend

Both flows converge at the same search and scoring pipeline. Flow B just adds the scan and Q&A in front.

What the Scan Actually Does

When you run /skillmama with no arguments, it reads:

Package files (package.json, pyproject.toml, go.mod, etc.)
Config and infra (Dockerfile, docker-compose.yml, .env.example, vercel.json, fly.toml)
README.md and CLAUDE.md
Source file structure (file listing, not full reads)
2–4 representative source files — the entry point, a route handler, a model

From that, it builds a Stack Profile:

Language:      TypeScript
Framework:     Next.js 14
Database:      Postgres via Prisma
Auth:          none detected
Caching:       none detected
AI/LLM:        OpenAI SDK
Queue/Jobs:    none detected
Search:        none detected
Storage:       none detected
Email:         none detected
Payments:      none detected
Observability: none detected
Testing:       Vitest

Gap Analysis: Not Everything Missing Is a Problem

Once the Stack Profile is built, SKILLmama doesn't just flag every empty row as a gap. It looks at what the project is actually doing and assigns severity:

High — typical for this type of app, likely needed soon
Medium — useful but not urgent
Low — speculative / nice-to-have

For a Next.js app with OpenAI already wired up, the output might look like this:

## SKILLmama — Project Scan

Stack detected: TypeScript / Next.js 14 / Postgres / OpenAI / no auth

Capability gaps found:

| # | Gap              | Severity | Why it matters for your stack                              |
|---|------------------|----------|------------------------------------------------------------|
| 1 | Authentication   | High     | No auth detected — any route is publicly accessible        |
| 2 | Rate limiting    | High     | OpenAI calls with no rate limiting = unbounded cost risk   |
| 3 | Observability    | Medium   | No error tracking — you'll find out about failures late    |
| 4 | Email sending    | Medium   | Common for Next.js apps with user accounts                 |
| 5 | Vector/RAG layer | Low      | OpenAI is present but no vector store — may be intentional |

A few quick questions before I search:
1. Which gap(s) would you like me to find options for?
2. Any constraints? (self-hosted, open-source, must have MCP support, etc.)
3. Anything I missed about your project or plans?

Then it stops. It does not proceed until you reply.

Why the Hard Stop Matters

The first version of this flow I sketched out just picked the highest-severity gap automatically and ran with it. That was wrong for two reasons:

1. Severity is relative to intent. A High gap for a consumer SaaS is a Low gap for an internal tool. The scanner doesn't know which one you're building — you do.

2. You might want to address multiple gaps in order. If you reply "1 and 2", SKILLmama runs the full search and scoring pipeline once per gap and presents each as its own results block. You get ranked picks for auth and rate limiting in one session, not just the first one.

The hard stop is what makes Flow B collaborative rather than presumptuous.

After You Answer

Once you reply — say "1 and 3, open-source preferred" — SKILLmama sets:

capability = Authentication, Observability
constraints = open-source preferred

And jumps straight to Phase 2 (deriving search terms). It skips Phase 0 and Phase 1 entirely — the stack is already known from the scan, so there's nothing left to parse.

From there, the same pipeline runs as always:

Phase 2 — derive search terms
Phase 3 — 5-tier search (GitHub → MCP → npm/PyPI → Templates)
Phase 3.5 — security gate (libraries)
Phase 3.6 — companion skills search
Phase 3.7 — security gate (skills)
Phase 4 — score each candidate
Phase 5 — present results

For the auth gap on a Next.js + Postgres stack, that produces something like:

Scoring all candidates against TypeScript / Next.js 14 / Postgres:

| Candidate   | Compat | Pop | Maint | Simple | Score    |
|-------------|--------|-----|-------|--------|----------|
| NextAuth.js | 10     | 9   | 9     | 9      | **9.55** |
| Lucia        | 9      | 7   | 10    | 8      | **8.75** |
| Clerk        | 8      | 8   | 10    | 10     | **8.90** |

#1 — NextAuth.js · Score: 9.55/10
The de facto auth layer for Next.js — first-party adapter, zero config for most providers.
- Compatibility: 10/10 — built for Next.js, Prisma adapter available
- Popularity:     9/10 — 22k stars, 800k npm downloads/week
- Maintenance:    9/10 — committed 1 week ago
- Simplicity:    9/10  — provider config only, Prisma adapter is one import
- Security:      PASS
- Install: npm install next-auth

What Changed in the Adapters

Flow B is live across all four adapters:

Adapter	How to trigger Flow B
Claude Code	`/skillmama` (no args)
Claude.ai	`/skillmama` (no args)
OpenAI Codex	`"scan my project and tell me what I need"`
Antigravity	`"scan my project and tell me what I need"`

Install

Any agent (via skills CLI):

npx skills add Magithar/SKILLmama

Claude Code:

npx skills add Magithar/SKILLmama -a claude-code

The -a claude-code flag matters: without it, non-interactive installs can silently skip wiring the skill into .claude/skills/, and /skillmama won't show up. Or copy the file directly:

cp .claude/commands/skillmama.md /your-project/.claude/commands/skillmama.md

Then /skillmama in any Claude Code session.

Claude.ai: Clone the repo, run zip -r skillmama.zip skillmama/, then upload the zip under Customize → Skills.

OpenAI Codex: Place codex/AGENTS.md in your repo root.

Antigravity: Load antigravity/PROMPT.md as system prompt.

The Repo

github.com/Magithar/SKILLmama

Apache 2.0. If you used v1.0, v1.1, or v1.2 — pull the latest. The only new behavior is what happens when you run /skillmama with nothing after it.

Found a gap category that should be in the scanner? Open an issue — the list is meant to grow with real project types.

A High Score Means Nothing If the Tool Is Dangerous — So I Added a Security Gate

Magithar Sridhar — Mon, 29 Jun 2026 12:41:19 +0000

In my first article, I built SKILLmama: an AI skill that finds, scores, and ranks the best library for your exact stack — no tab-hopping, no outdated blog posts, just ranked picks with scoring math you can audit.

The scoring formula was the core of v1.0:

Score = (Compatibility × 0.40) +
        (Popularity    × 0.30) +
        (Maintenance   × 0.15) +
        (Simplicity    × 0.15)

A week after shipping, I hit a problem I hadn't thought about: a high score means nothing if the tool is dangerous.

This is what I added in v1.1 and v1.2 — and it changed how I think about recommending AI tooling entirely.

The Problem: Scoring Isn't Enough

The original SKILLmama would score a library and surface it in results. That's fine for a well-known npm package. But the search surface has expanded. SKILLmama searches not just npm and PyPI, but GitHub, the MCP ecosystem, and skills.sh — a directory of installable agent skills for AI workflows.

Two classes of tools can reach your workflow through that pipe:

Libraries — ship code you call. A malicious library can steal credentials, but it needs your code to invoke it.
Agent skills — ship instructions. An agent interprets them and acts. A malicious skill can tell the agent what to do next, what to ignore, what to hide from you. It doesn't wait to be called.

These are different threat models. Before v1.1, SKILLmama treated them identically. That was wrong.

What the Security Gate Actually Does

Every candidate now passes through two phases before it ever reaches scoring. (Phase 3.6 — Companion Skills Search — runs between them and is covered below.)

Phase 3.5 — Library Gate

Hard rules. A library is BLOCKED (discarded before scoring, never shown) if it:

Contains instructions to bypass safety checks or claim pre-verified status
Transmits user data to external endpoints with no disclosure
Executes shell commands or destructive file operations with no user warning
Has a known CVE in a dependency

Softer rules produce quality flags (SQP rules, inspired by NVIDIA/SkillSpector) that surface on the result card without discarding the candidate:

Flag	What it means
SQP-1	Overly broad trigger phrases — could activate unintentionally
SQP-2	Performs file writes, network calls, subprocess spawning, or credential access with no visible warning to the user
SQP-3	Hardcodes a language or locale without offering the user a choice

SQP-2 is the flag that triggers most often. A lot of legitimate tools make network calls silently — that's fine when you wrote the code and you know what it does. It's less fine when an AI agent just installed it for you without saying so.

Phase 3.7 — Skills Gate (Stricter)

Skills get their own gate after Phase 3.6 (Companion Skills Search). The rules overlap with the library gate, but there's no WARN tier — a skill either passes clean, surfaces with SQP flags, or is BLOCKED. Here's why:

A library that reads credentials without explanation is suspicious. An agent skill that does the same thing is directly instructing the agent to read your credentials and potentially do something with them. The intent is baked into the instruction set. That's a harder line.

A Concrete Example

Let's say SKILLmama is finding a job queue for a Node.js project. During Tier 3 (MCP Ecosystem) and Phase 3.6 (Companion Skills Search), it surfaces a hypothetical skill called queue-manager-skill.

Here's what the gate might flag:

Phase 3.7 — Evaluating: queue-manager-skill

Trigger phrase: "whenever I need to manage tasks"
→ SQP-1: overly broad — no exclusion conditions, could fire on unrelated requests

On each job completion:
  POST job_result to https://analytics.queuemanager-cloud.io
→ SQP-2: network call with no user disclosure

Result: ⚠️ SQP-1, SQP-2 — surfaces in Companion Skills with flags visible

The skill isn't blocked — it might be legitimate, and you might decide the analytics endpoint is fine. But you see it before installing anything. That's the point.

Compare to a library result:

#1 — BullMQ · Score: 9.10/10
Redis-backed job queue, official Node.js SDK, 15k GitHub stars.
- Compatibility: 10/10 — native Node/TypeScript, full Express integration
- Popularity:     9/10 — 15k stars, 1.2M npm downloads/week
- Maintenance:   10/10 — committed 3 days ago
- Simplicity:    8/10  — Redis required, well-documented setup
- Security:      PASS

PASS means it cleared all hard gates, no SQP flags. You can install it without reading fine print.

Why the Output Doesn't Shout About It

One deliberate decision: Phases 3.5 and 3.7 don't appear as sections in the output. There's no "Security Report" block. Security findings appear inline on each candidate card only.

The reason: if security is a separate section, developers scroll past it. If it's on the card, it's part of the decision — you see the score and the security line together. A PASS blends into the card. An ⚠️ SQP-2 stands out where it matters.

Blocked candidates are silently discarded — they never appear in results, never in "Also Considered." If something is genuinely dangerous, you don't need to know it lost; you just don't see it.

Companion Skills: Why This Became Necessary

In v1.2, SKILLmama added Phase 3.6: after finding library candidates, it also searches skills.sh and GitHub for installable agent skills that pair with top picks.

For the vector database example from the first article, that looks like:

Companion Skills:
- qdrant-memory-skill (skills.sh) — Security: PASS
  Adds Qdrant as persistent memory for your AI agent; install alongside qdrant-client

This is where the stricter gate on skills stopped being theoretical. Once SKILLmama was actively surfacing skills alongside libraries, it needed to actually evaluate them — not assume that anything on skills.sh was safe by virtue of being listed there. The ecosystem is too new for that assumption to hold.

The threshold I landed on: anything that an agent will interpret as instructions gets a harder gate than code you call yourself. You can audit code. Instructions are harder to reason about at a glance — that asymmetry is why the gate is stricter.

What This Looks Like in Practice

Full output for /skillmama find me a job queue for my Node.js + Redis project:

Scoring all candidates against Node.js / Redis / Express:

#1 — BullMQ · Score: 9.10/10
Redis-backed queue with full TypeScript support and battle-tested at scale.
- Compatibility: 10/10 — built for Node/Redis, native TypeScript
- Popularity:     9/10 — 15k stars, 1.2M downloads/week
- Maintenance:   10/10 — committed 3 days ago
- Simplicity:    8/10  — Redis required, excellent docs
- Security:      PASS
- Install:        npm install bullmq

#2 — bee-queue · Score: 7.85/10
Lighter alternative; fewer features, faster setup.
- Compatibility:  9/10 — Node/Redis native
- Popularity:     6/10 — 3.5k stars, 180k downloads/week
- Maintenance:    8/10 — committed 2 weeks ago
- Simplicity:    9/10  — minimal config, fast local setup
- Security:      PASS

Also Considered: Agenda (MongoDB-based, no Redis dep), p-queue (in-process only)

Companion Skills:
- bullmq-agent-skill · ⚠️ SQP-2 — performs Redis writes with no user confirmation prompt
  Automates job scheduling from natural language; review before installing

Next Steps:
1. npm install bullmq and spin up Redis via docker run redis to validate locally
2. If you want to skip Redis infra, evaluate Agenda — MongoDB-native
3. Review the SQP-2 flag on bullmq-agent-skill before installing in any automated pipeline

Install

Any agent (via skills CLI):

npx skills add Magithar/SKILLmama

Claude Code:

npx skills add Magithar/SKILLmama -a claude-code

The -a claude-code flag matters: without it, non-interactive installs can silently skip wiring the skill into .claude/skills/, and /skillmama won't show up. Or copy the file directly:

cp .claude/commands/skillmama.md /your-project/.claude/commands/skillmama.md

Then /skillmama in any Claude Code session.

Claude.ai: Clone the repo, run zip -r skillmama.zip skillmama/, then upload the zip under Customize → Skills.

OpenAI Codex: Place codex/AGENTS.md in your repo root.

Antigravity: Load antigravity/PROMPT.md as system prompt.

The Repo

github.com/Magithar/SKILLmama

Apache 2.0. The security gate is live across all four adapters. If you used v1.0, pull the latest. The only user-visible changes are the Security: line on each result card and a Companion Skills section when agent skills are found.

Security findings from real use? Drop them in the issues — the SQP ruleset is meant to grow.

A Deterministic Scoring Engine That Finds the Best Library for Your Exact Stack

Magithar Sridhar — Fri, 19 Jun 2026 02:17:07 +0000

Every developer knows this feeling.

You need a vector database. Or a job queue. Or a .dwg parser for Node.js. You open a browser tab, search GitHub, open five more tabs, try to compare stars and last-commit dates, get distracted by a Medium post from 2019, and 45 minutes later you've picked something based on vibes.

There's a better way. I built it.

SKILLmama finds, scores, and ranks the best library, SDK, or tool for your exact stack — no tab-hopping, no outdated blog posts, just ranked picks with scoring math you can audit.

It works with Claude Code, Claude.ai, OpenAI Codex, and Antigravity.

The Problem With How We Pick Libraries

Most library selection looks like this:

Google "best [thing] for [framework]"
Find a Reddit thread from 3 years ago
Pick the one with the most upvotes
Discover 6 months later that it hasn't been maintained since 2021

The real question isn't "what's popular" — it's "what fits my stack, has active maintenance, won't take a week to integrate, and is popular enough to have community support?" Those are four separate signals, and you need all four weighted correctly.

The Scoring Formula

SKILLmama scores every candidate on four dimensions:

Score = (Compatibility × 0.40) +
        (Popularity    × 0.30) +
        (Maintenance   × 0.15) +
        (Simplicity    × 0.15)

Factor	Weight	What it measures
Compatibility	40%	Language/framework fit, official SDK, integration effort
Popularity	30%	GitHub stars, npm/PyPI weekly downloads
Maintenance	15%	Days since last commit, release cadence
Simplicity	15%	Setup effort, documentation quality

Compatibility is weighted highest because a library built for Java won't help you in a Python project, no matter how popular it is. Popularity comes second because the ecosystem around a library matters. Maintenance and simplicity round it out.

Every score is 1–10 per dimension. No black box. You can see exactly why something ranked #1.

The 5-Tier Search Hierarchy

SKILLmama doesn't just search one place. It works through five tiers in order, stopping when it has 8+ candidates:

Tier	Source	What it finds
1	skills.sh	Reusable skills and capability patterns
2	GitHub	Open-source libraries, frameworks, SDKs
3	Smithery / MCP Ecosystem	AI-native tools installable as MCP servers
4	npm / PyPI / pkg.go.dev	Package registries with download signals
5	Curated Templates	LangGraph, OpenHands, cookbook examples

Tier 3 is the interesting one. The MCP ecosystem is growing fast — if there's an MCP server for your capability, you might be able to plug it directly into your AI workflow instead of writing integration code. SKILLmama surfaces that option explicitly.

The Security Gate

But a high score means nothing if the tool is unsafe. Before any candidate gets scored, it passes through a two-layer security and quality check.

The hard gate discards candidates that are genuinely unsafe: CVE dependencies, undisclosed data exfiltration, jailbreak instructions, or destructive operations with no user warning. These never reach the scoring phase.

The quality flags (SQP rules, inspired by NVIDIA/SkillSpector) surface softer issues without discarding the candidate:

SQP-1 — Vague trigger phrases that could activate unintentionally
SQP-2 — Missing warnings on file writes, network calls, or credential access
SQP-3 — Hardcoded language or locale without user opt-in

Every result card shows a Security line: PASS, ⚠️ SQP-2 — [finding], or 🚫 BLOCKED. You always know what you're installing. No surprises. No silent risks.

How It Works

┌─────────────────────────────────────────────────────────┐
│                      USER REQUEST                       │
└─────────────────────────┬───────────────────────────────┘
                          │
                          ▼
              ┌───────────────────────┐
              │   PHASE 0             │
              │   Understand Request  │
              │   Extract: capability,│
              │   stack, constraints  │
              └───────────┬───────────┘
                          │
                          ▼
                   ◇ Capability
                     vague?
                   /         \
                 YES           NO
                  │             │
                  ▼             │
          Ask 1 clarifying      │
          question, await       │
          user response         │
                  │             │
                  └──────┬──────┘
                         │
                         ▼
              ┌───────────────────────┐
              │   PHASE 1             │
              │   Architecture Scan   │
              └───────────┬───────────┘
                          │
                          ▼
                   ◇ In a project
                     repo?
                   /         \
                 YES           NO
                  │             │
                  ▼             │
        Read: package.json,     │
        Dockerfile, README,     │
        source files            │
                  │             │
                  └──────┬──────┘
                         │
                         ▼
              ┌───────────────────────┐
              │   PHASE 2             │
              │   Capability Gap      │
              │   Detection           │
              │                       │
              │   Define:             │
              │   CAPABILITY          │
              │   STACK               │
              │   CONSTRAINTS         │
              │   SEARCH_TERMS (3–5)  │
              └───────────┬───────────┘
                          │
                          ▼
              ┌───────────────────────┐
              │   PHASE 3             │
              │   5-Tier Search       │
              └───────────┬───────────┘
                          │
              Tier 1 ── skills.sh
                 ↓
              Tier 2 ── GitHub (stars, recency, contrib)
                 ↓
              Tier 3 ── MCP Ecosystem
                 ↓
              Tier 4 ── npm / PyPI registries
                 ↓
              Tier 5 ── Templates & Cookbooks
                          │
                   ◇ 8+ candidates found?
                   /              \
                 YES               NO
                  │                │
            Skip remaining    Continue tiers
            tiers                  │
                  └──────┬─────────┘
                         │
                         ▼
              ┌────────────────────────────────────────┐
              │   PHASE 3.5 — Security & Quality Gate  │
              │                                        │
              │   Hard Gate:                           │
              │   🚫 BLOCKED → discard, never score    │
              │   ⚠️  WARN   → show, user confirms     │
              │                                        │
              │   Quality flags (SQP rules):           │
              │   SQP-1  Vague triggers                │
              │   SQP-2  Missing user warnings         │
              │   SQP-3  Policy violations             │
              └───────────────┬────────────────────────┘
                              │
                              ▼
              ┌────────────────────────────────────────┐
              │   PHASE 4 — Score Each Candidate       │
              │                                        │
              │   Score = (C × 0.40) +                 │
              │           (P × 0.30) +                 │
              │           (M × 0.15) +                 │
              │           (S × 0.15)                   │
              └───────────────┬────────────────────────┘
                              │
                              ▼
              ┌────────────────────────────────────────┐
              │   PHASE 5 — Present Results            │
              │                                        │
              │   #1, #2, #3 — full score breakdown    │
              │   Also Considered — table              │
              │   MCP callout (if found)               │
              │   Next Steps (3 actions)               │
              └────────────────────────────────────────┘

End-to-End Example

Prompt:

/skillmama find me a vector database for my FastAPI + Python project

Phase 1 — Architecture Scan

SKILLmama reads your project files first:

✓ pyproject.toml  → Python 3.11, FastAPI, SQLAlchemy
✓ Dockerfile      → containerized, no GPU
✓ .env.example    → OPENAI_API_KEY present → RAG use case confirmed

Detected stack: Python / FastAPI / PostgreSQL / Docker / OpenAI

Phase 2 — Capability Gap Detection (runs internally)

CAPABILITY : vector database for RAG / semantic search
STACK      : Python / FastAPI / Docker / OpenAI
CONSTRAINTS: containerizable, Python client, active maintenance

Phase 3 — 5-Tier Search

Tier 1 skills.sh  → "qdrant-memory-skill", "chroma-rag-skill"
Tier 2 GitHub     → qdrant (17k★), chroma (14k★), pgvector (11k★), milvus (29k★)
Tier 3 MCP        → qdrant-mcp-server, chroma-mcp
Tier 4 PyPI       → qdrant-client (380k/wk), chromadb (620k/wk), pgvector (180k/wk)
Tier 5 Templates  → LangChain + Qdrant RAG template, FastAPI + Chroma starter

Phase 4 — Scoring

Candidate	Compat	Popular	Maint	Simple	Score
Qdrant	9	8	10	9	9.05
pgvector	10	7	9	7	8.65
Chroma	8	8	9	10	8.55
Milvus	6	9	10	4	7.05

Phase 5 — Output

#1 — Qdrant · Score: 9.05/10
Docker-native, official Python client, active MCP server for AI workflows.
- Compatibility: 9/10  — official qdrant-client SDK, FastAPI examples in docs
- Popularity:    8/10  — 17k GitHub stars, 380k PyPI downloads/week
- Maintenance:  10/10  — committed 2 days ago, weekly releases
- Simplicity:   9/10  — docker run + pip install, 5-min setup
- Security:     PASS  — no findings
- Install: docker run -p 6333:6333 qdrant/qdrant && pip install qdrant-client

#2 — pgvector · Score: 8.65/10
Stay on PostgreSQL — no new infra, native SQL queries.

#3 — Chroma · Score: 8.55/10
Easiest local dev setup; best for prototyping before scaling.

MCP Option: qdrant-mcp-server — install as MCP tool for direct AI memory integration.

Next Steps:
1. docker run qdrant/qdrant and pip install qdrant-client to validate locally
2. Use the LangChain + Qdrant RAG template as a starting point
3. If staying Postgres-only, evaluate pgvector — saves an infra hop

That's 45 minutes of tab-hopping, compressed into a structured decision.

Install in 4 AI Systems

Claude Code:

mkdir -p /your-project/.claude/commands
cp .claude/commands/skillmama.md /your-project/.claude/commands/skillmama.md

Then type /skillmama in any Claude Code session.

Claude.ai:

Clone the repo
zip -r skillmama.zip skillmama/
Go to Customize → Skills → + and upload the zip
Type /skillmama in any conversation

OpenAI Codex:
Place codex/AGENTS.md in your repo root, then ask naturally:

codex "find me the best job queue for this project"

Antigravity:
Load antigravity/PROMPT.md as the system prompt, then ask naturally.

All four adapters run the same pipeline and produce the same output format.

What SKILLmama Is Not

Not an IDE. Not autocomplete. Not a chatbot.

It's a capability oracle — it tells you what to use and why, with evidence. You still write the code. SKILLmama just makes sure you're writing it with the right tool.

The Repo

github.com/Magithar/SKILLmama

Apache 2.0 licensed. Works with Claude Code, Claude.ai, OpenAI Codex, and Antigravity.

/skillmama find me a vector database for my FastAPI project
/skillmama what auth library should I use for my Next.js app?
/skillmama scan my project and tell me what's missing
/skillmama find a .dwg parser for Node.js

Try it on your next project: github.com/Magithar/SKILLmama. If you've ever spent an afternoon picking the wrong library, I'd love to hear what you wish you'd known sooner.

If SKILLmama saves you time, a ⭐ on the repo goes a long way — it helps other developers find it.

The Game Identity Registry Pattern — Bridging Mirror netId and Socket.IO playerId

Magithar Sridhar — Sun, 03 May 2026 00:05:04 +0000

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?

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.

DEV Community: Magithar Sridhar

The Bug Was in My Own Instructions, Not My Code

The Recording

The Wrong Guesses

The Real Answer Was in the Docs I Hadn't Read

Closing the Loop

Bonus: While I Was In There

What Changed

10 Common Unity Networking Issues (and How to Fix Them)

1. Reconnect wipes your room/namespace state

2. "get_gameObject can only be called from the main thread"

3. Connect() hangs with no timeout

4. WebGL builds behave nothing like the Editor

5. IL2CPP stripping deletes types that only exist at runtime

6. A malformed binary packet crashes the whole handler pipeline

7. "Heartbeat timeout" that isn't actually a network problem

8. Namespace/room auth fails silently

9. Reflection-based config breaks silently when a dependency renames a field

10. Two reconnect timers running at once

The common thread

A Reader Pointed Out My "Ask First" Principle Only Covered Half My Tool — So I Fixed It

The Hole

The Fix: Phase 1.5

The Three Rules That Keep It From Being Annoying

Why "One Informed Question" Beats "A Form"

What Changed

I Got Tired of Asking "What Am I Missing?" — So I Made My AI Ask First

The Old Flow vs. The New Flow

What the Scan Actually Does

Gap Analysis: Not Everything Missing Is a Problem

Why the Hard Stop Matters

After You Answer

What Changed in the Adapters

Install

The Repo

A High Score Means Nothing If the Tool Is Dangerous — So I Added a Security Gate

The Problem: Scoring Isn't Enough

What the Security Gate Actually Does

Phase 3.5 — Library Gate

Phase 3.7 — Skills Gate (Stricter)

A Concrete Example

Why the Output Doesn't Shout About It

Companion Skills: Why This Became Necessary

What This Looks Like in Practice

Install

The Repo

A Deterministic Scoring Engine That Finds the Best Library for Your Exact Stack

The Problem With How We Pick Libraries

The Scoring Formula

The 5-Tier Search Hierarchy

The Security Gate

How It Works

End-to-End Example

Install in 4 AI Systems

What SKILLmama Is Not

The Repo

The Game Identity Registry Pattern — Bridging Mirror netId and Socket.IO playerId

The Pattern

Registration — When and Where

Usage — Routing Backend Events

Cleanup — When and Where

Why Static?

The Broader Pattern

The Full Context

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

3. `Connect()` hangs with no timeout