v1.5.0 —Dedicated Server Support for Mirror Integration

Adds dedicated server support to the Mirror Integration sample with three selectable server modes (P2P, KCP, WebSocket), and fixes transport port injection for SimpleWebTransport and MultiplexTransport.

---

📦 Installation

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

Or in Packages/manifest.json:

{
  "dependencies": {
    "com.magithar.socketio-unity": "https://github.com/Magithar/socketio-unity.git?path=/package#v1.5.0"
  }
}

---

✨ What's New

⚙️ Dedicated Server Support (Mirror Integration)

• ServerMode enum (PeerToPeer, DedicatedKCP, DedicatedWebSocket) — inspector dropdown on MirrorGameOrchestrator; replaces the single P2P-only code path

• DedicatedKCP mode — all clients connect to hostAddress:kcpPort after match_started; intended for native (non-WebGL) builds

• DedicatedWebSocket mode — all clients connect to hostAddress:wsPort; intended for WebGL builds

• FindTransport helper — walks MultiplexTransport children to locate the correct transport by type name, so Multiplex + KCP/SWT setups are handled correctly

• Transport port set via reflection — sample compiles without hard dependencies on kcp2k or SimpleWebTransport packages

---

🌐 Server & Networking

• kcpPort / wsPort in match_started — mirror-server.js reads MIRROR_SERVER_ADDRESS, MIRROR_KCP_PORT, MIRROR_WS_PORT env vars; dedicated-server values take priority over the client-provided P2P host address; both ports forwarded in match_started to all room members

---

⚠️ Breaking Changes

• LobbyStateStore.OnMatchStarted (Lobby / MirrorIntegration samples only) — event delegate type changed from Action<string, string> to Action<string, string, int, int>; if you copied LobbyUIController, GameOrchestrator, or MirrorGameOrchestrator from v1.4.0 and subscribed to this event, add int kcpPort, int wsPort parameters to your handler. The core Socket.IO client is unaffected.

---

🔧 Changes & Fixes

• LobbyStateStore.FireMatchStarted — gains optional kcpPort/wsPort params (default 0) for callers that don't use dedicated-server ports

• LobbyNetworkManager — parses kcpPort and wsPort from the match_started JSON payload and passes them through to FireMatchStarted

• SimpleWebTransport port reflection — corrected field name lookup; added property fallback so DedicatedWebSocket mode correctly overrides the port even when the transport exposes it as a property rather than a field

• MultiplexTransport port injection — FindTransport now searches the transports array on MultiplexTransport so the correct child transport is found rather than silently falling back to the inspector value

• README & MirrorIntegration README — describes all three server modes, links to the companion dedicated-server repo, rewrote Session Timeline into four headed subsections with a server-mode comparison table

---

🔗 Links

• Full Changelog
• Mirror Integration Sample
• Mirror Server Repo

---

v1.4.0 — Mirror Integration, Repo Restructure, WebGL Fixes

Adds Mirror Integration sample for hybrid Socket.IO + Mirror networking, restructures the repo under a package/ subdirectory, and consolidates samples for cleaner imports.

---

📦 Installation

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

Or in Packages/manifest.json:

{
  "dependencies": {
    "com.magithar.socketio-unity": "https://github.com/Magithar/socketio-unity.git?path=/package#v1.4.0"
  }
}

---

✨ What's New

⚙️ Mirror Integration Sample

• MirrorGameOrchestrator — enforces startup/teardown order for lobby→match transitions; dual guard against duplicate match_started events

• GameIdentityRegistry — bridges Mirror netId to Socket.IO playerId for routing backend events to the correct spawned object

• PlayerIdentityBridge — registers player identity on spawn via Mirror [Command] and syncs lobby display names to all clients

• GameEventBridge — subscribes to /game namespace events only after match_started; never active during lobby phase

• MirrorPlayerController — local player input only; red = local, blue = remote

• Graceful shutdown — emits leave_room before stopping Mirror to skip the 10-second reconnect grace window

---

🌐 Server & Networking

• mirror-server.js (port 3002) — extends lobby server with /game namespace and HTTP endpoints (/test/score, /test/kill, /test/round-end)

• hostAddress in match_started — server-assigned LAN IP forwarded through the full event chain for Mirror P2P host mode; JS "undefined"/"null" normalized to C# null

---

🧪 Testing & CI

• ConnectionState runtime tests — NUnit tests covering connection state transitions

• GitHub Pages deployment workflow — automated live demo deployment on push to main

• Test assemblies — removed UNITY_INCLUDE_TESTS constraint; tests now compile on all platforms

---

⚠️ Changes

• Repo restructured — all package content moved under package/ subdirectory. Install URL now requires ?path=/package.

• Samples consolidated — SocketIOManager and SocketIODiagnosticsOverlay moved into Samples~/BasicChat/

• Lobby asmdef added — allows MirrorIntegration to reference Lobby types without circular dependencies

• No API changes — fully backward compatible

---

🔗 Links

• Full Changelog
• Mirror Integration Sample

---

v1.3.1 — WebGL Fixes & LiveDemo Server

Fixes WebGL lobby issues (ACK handling, IL2CPP stripping), adds a combined LiveDemo server for easier deployment, and improves build size with compressed assets.

📦 Installation

https://github.com/Magithar/socketio-unity.git#v1.3.1

Or in Packages/manifest.json:

"com.magithar.socketio-unity": "https://github.com/Magithar/socketio-unity.git#v1.3.1"

---

✨ What's New

⚙️ Core

• Combined LiveDemo server (livedemo-server.js) — single-process server for /lobby and /playersync
• Runtime link.xml — prevents IL2CPP stripping of critical runtime types
• Lobby link.xml — preserves RoomState and LobbyPlayer for WebGL builds

---

🧪 Fixes

• WebGL ACK handling — correctly unwraps Socket.IO array responses (fixes room create/join)
• IL2CPP stripping issues — fixes silent JSON deserialization failures in WebGL

---

🌐 Platform

• Compressed WebGL builds (.unityweb) — significantly smaller download size
• LiveDemo uses production server instead of localhost

---

⚠️ Changes

• Improved WebGL build pipeline and deployment flow
• No API changes — fully backward compatible

---

🔗 Links

• Full Changelog
• LiveDemo Sample

v1.3.0 — Live Demo & Diagnostics

Introduces an end-to-end multiplayer Live Demo combining Lobby and PlayerSync, along with diagnostics tools, connection state tracking, and improved reconnect stability.

📦 Installation

https://github.com/Magithar/socketio-unity.git#v1.3.0

Or in Packages/manifest.json:

"com.magithar.socketio-unity": "https://github.com/Magithar/socketio-unity.git#v1.3.0"

---

✨ What's New

⚙️ Core

• Typed SocketError (Transport, Auth, Timeout, Protocol) replaces string errors
• ConnectionState enum + State property + OnStateChanged event
• Namespace persistence across reconnects (no re-registration needed)

---

🧪 Testing

• Integration tests for lobby/socket state
• Stress tests: high load, large payloads, ACK storms, reconnect cycles, memory checks
• InternalsVisibleTo for deeper test access

---

🖥️ Samples

• Diagnostics Overlay (Samples~/Diagnostics/)

  • Shows state, RTT, namespaces, ACKs, event log

• LiveDemo (Samples~/LiveDemo/)

  • End-to-end Lobby + PlayerSync with seamless transitions

---

🌐 Platform

• Per-sample servers (:3000–3003)
• WebGL clipboard support
• player_identity handling (fixes host race condition)

---

⚠️ Changes

• Breaking: OnError → Action<SocketError>
• Improved WebSocket lifecycle (safer reconnects, event rebinding)

---

🔄 Migration

// Before
socket.OnError += (string msg) => Debug.LogError(msg);

// After
socket.OnError += (SocketError err) =>
    Debug.LogError($"[{err.Type}] {err.Message}");

---

🔗 Links

• Full Changelog
• Diagnostics Sample
• LiveDemo Sample

v1.2.0 — Lobby Sample

Introduces a production-style multiplayer Lobby sample with reconnect recovery and automatic host migration. No API changes — fully backward compatible with v1.1.2.

📦 Installation

https://github.com/Magithar/socketio-unity.git#v1.2.0

Or in Packages/manifest.json:

"com.magithar.socketio-unity": "https://github.com/Magithar/socketio-unity.git#v1.2.0"

---

✨ What's New

🏠 Lobby Sample (Samples~/Lobby/)

A production-style multiplayer lobby demonstrating real-world patterns:

• Room creation and join-by-code — 6-character codes (e.g. C9N7GR)
• Persistent identity — playerId + sessionToken stored in PlayerPrefs, survives crashes and app restarts
• Session token validation on reconnect prevents player slot spoofing
• 10-second reconnect grace window — room slot held while player is offline; host migration fires automatically
• Three-layer architecture: LobbyNetworkManager (transport) → LobbyStateStore (state) → LobbyUIController (view)
• Room version tracking and player list diffing — no full list rebuilds on updates
• Full WebGL support via TransportFactoryHelper.CreateDefault()
• Separate lobby-server.js on port 3001

📦 Package Manager Integration

• All three samples (Basic Chat, Player Sync, Lobby) now appear in the Unity Package Manager Samples tab via the package.json samples array

---

✅ Compatibility Guarantees

• Zero API Changes — New sample only, no core changes
• 100% Backward Compatible — Safe upgrade from v1.1.2
• No Configuration Changes — No changes to public interfaces or behavior

---

🔄 Upgrading from v1.1.2

No breaking changes — simply update the package version.

No configuration changes required.

---

🔗 Links

• Full Changelog
• Lobby Sample
• PlayerSync Sample

v1.1.2 — Reconnection Stability Fixes

Minor patch release improving reconnection stability and fixing several edge cases in the Socket.IO engine lifecycle. Fully backward compatible with v1.1.1.

📦 Installation

https://github.com/Magithar/socketio-unity.git#v1.1.2

Or in Packages/manifest.json:

"com.magithar.socketio-unity": "https://github.com/Magithar/socketio-unity.git#v1.1.2"

---

🐛 What's Fixed

🔌 Reconnection Stability

• SocketIOClient.CreateFreshEngine() — Fully recreates engine, namespaces, and binary assembler on each reconnect, preventing stale state from a previous connection leaking into the new one
• SocketIOClient.Tick() — Caches the namespace list before iterating to avoid an InvalidOperationException (collection modified during enumeration) that could occur mid-reconnect
• SocketIOClient.HandleEngineClose() — Added race-condition guard (if (IsConnected) return) and calls _namespaces.ResetAll() before invoking disconnect handlers, preventing double-teardown and ensuring namespace state is clean before user code runs
• SocketIOClient.HandleEngineMessage() — Re-registers all non-root namespaces after reconnect by sending CONNECT packets; namespaces were silently dropped after a reconnect cycle
• SocketIOClient.DestroyEngine() / AttemptReconnect() — Separated teardown and reconnect attempt into distinct methods for clarity and correctness

🎮 PlayerSync Sample

• PlayerNetworkSync — Re-attaches socket event handlers on reconnect to match the core reconnection fixes

---

✅ Compatibility Guarantees

• Zero API Changes — All fixes are internal implementation changes
• 100% Backward Compatible — Safe upgrade from v1.1.1
• No Configuration Changes — No changes to public interfaces or behavior

---

🔄 Upgrading from v1.1.1

No breaking changes — simply update the package version.

No configuration changes required.

---

🔗 Links

• Full Changelog
• PlayerSync Sample

v1.1.1 - PlayerSync Label Rendering Fixes

Minor patch release fixing PlayerSync label rendering issues and adding a camera-facing billboard system. Fully backward compatible with v1.1.0.

---

📦 Installation

https://github.com/Magithar/socketio-unity.git#v1.1.1

Or in Packages/manifest.json:

"com.magithar.socketio-unity": "https://github.com/Magithar/socketio-unity.git#v1.1.1"

---

🐛 What's Fixed

🎮 PlayerSync --- RemotePlayer Label Rendering

• Canvas render mode corrected from Screen Space - Overlay to World Space
• Fixed Canvas.transform.localScale being (0, 0, 0) which made the label invisible
• Fixed RectTransform.sizeDelta being (0, 0) which prevented text rendering
• Label now properly renders above the player in 3D space

These fixes are isolated to the PlayerSync sample assets.

---

✨ What's New

🎯 BillboardCanvas Script

• New BillboardCanvas component added to RemotePlayer Canvas child
• Copies camera rotation in LateUpdate()
• Ensures player name label always faces the viewer
• Works regardless of camera angle or player direction
• Zero impact on networking or runtime API

---

✅ Compatibility Guarantees

• Zero API Changes --- Core networking APIs unchanged
• 100% Backward Compatible --- Safe upgrade from v1.1.0
• Sample-Only Changes --- No runtime behavior changes in production usage

---

🔄 Upgrading from v1.1.0

No breaking changes --- simply update the package version.

No configuration changes required.

---

🔗 Links

• Full Changelog
• PlayerSync Sample

v1.1.0 — Configurable Reconnection & CI Pipeline

Minor release adding configurable reconnection strategy, a new multiplayer sample, and automated CI. Fully backward compatible with v1.0.x.

---

📦 Installation

https://github.com/Magithar/socketio-unity.git#v1.1.0

Or in Packages/manifest.json:

"com.magithar.socketio-unity": "https://github.com/Magithar/socketio-unity.git#v1.1.0"

---

✨ What's New

⚙️ Configurable Reconnection Strategy

• New ReconnectConfig struct replaces hardcoded exponential backoff
• Configurable initialDelay, multiplier, maxDelay, maxAttempts, autoReconnect, jitterPercent
• ReconnectConfig.Default() — matches v1.0.x behavior (1s initial, 2× multiplier, 30s cap)
• ReconnectConfig.Aggressive() — faster reconnection for development
• ReconnectConfig.Conservative() — slower reconnection for production
• Jitter support prevents thundering herd on mass reconnect
• SocketIOClient.ReconnectConfig property for runtime configuration changes

🎮 PlayerSync Sample

• Real-time multiplayer position synchronization demo
• Demonstrates namespace pattern (/playersync), ReconnectConfig integration, and WebGL support
• Production-grade cleanup with OnDestroy, isDestroyed guard, and explicit disconnect
• Includes RTT display, connection status UI, and network interpolation

🤖 GitHub Actions CI Pipeline

• Automated EditMode tests on every push and PR to main via game-ci/unity-test-runner
• Unity 2022.3.62f2 (LTS) on ubuntu-latest
• Library/ folder cached for faster runs; test results uploaded as artifacts on every run

---

🐛 What's Fixed

🔧 EditMode / CI Stability

• DontDestroyOnLoad now skipped in EditMode and CI where Application.isPlaying is false
• Prevents errors when running automated tests outside of Play Mode

---

✅ Compatibility Guarantees

• Zero Breaking Changes — All public APIs (Connect, Disconnect, Emit, On, Off, Of) unchanged
• 100% Backward Compatible — Drop-in replacement for v1.0.x
• Behavior Preserved — ReconnectConfig.Default() exactly reproduces v1.0.x reconnection behavior

---

🔄 Upgrading from v1.0.x

No breaking changes — just update the package version. Optionally adopt ReconnectConfig to customize reconnection behavior.

// Optional: customize reconnect strategy (Default behavior unchanged if omitted)
client.ReconnectConfig = ReconnectConfig.Conservative();

---

🔗 Links

• Full Changelog
• PlayerSync Sample

v1.0.1 - Critical Stability Fixes

Critical patch release fixing production stability issues. Safe upgrade from v1.0.0 with full backward compatibility.

---

📦 Installation

https://github.com/Magithar/socketio-unity.git#v1.0.1

Or in Packages/manifest.json:

"com.magithar.socketio-unity": "https://github.com/Magithar/socketio-unity.git#v1.0.1"

---

🐛 What's Fixed

🔧 Unity Domain Reload Safety

• Fixed static dictionary memory leak in WebSocket.cs (NativeWebSocket dependency)
• Added ResetStatics() method to clear orphaned WebSocket instances on domain reload
• Prevents memory leaks across Unity Editor play mode sessions

🛡️ Binary Event Robustness

• Added try-catch protection in BinaryPacketAssembler
• Gracefully handles malformed JSON payloads
• Prevents unhandled exceptions on invalid binary event data

🔌 Reconnection Stability

• Fixed transport event nullification bug in WebSocketTransport.Close()
• Proper reconnection lifecycle restored

🔢 ACK Registry Overflow Protection

• Fixed ACK ID integer overflow after 2 billion emits
• ACK IDs now wrap to 1 when overflowing

---

✅ Stability Guarantees

• Zero API Changes — All fixes are internal implementation improvements
• 100% Backward Compatible — Drop-in replacement for v1.0.0
• License Compliant — NativeWebSocket modifications documented in NOTICE.md

---

🔄 Upgrading from v1.0.0

No breaking changes — just update the package version.

# Unity Package Manager → Update to v1.0.1
# OR update manifest.json to v1.0.1

---

🔗 Links

• Full Changelog
• NativeWebSocket Modifications

v1.0.0 — Production Stable

The first stable, production-ready release with a frozen public API contract. All v1.x releases will maintain backward compatibility.

📦 Installation

https://github.com/Magithar/socketio-unity.git#v1.0.0

Or in Packages/manifest.json:

"com.magithar.socketio-unity": "https://github.com/Magithar/socketio-unity.git#v1.0.0"

✨ What's New

🔒 API Stability Contract

• Public API frozen for all v1.x releases (Connect, Disconnect, Emit, On, Off, Of)
• Internal implementation fully encapsulated
• Debug & telemetry APIs explicitly marked as unstable
• Full contract documented in API_STABILITY.md

🛡️ Protocol Hardening

• 38 new edge-case tests added
• Malformed packet handling improvements
• Namespace disconnect correctness fixes
• Binary payload validation

🔁 Lifecycle Reliability

• Scene reload & domain reload safety verified
• Proper intentional vs unintentional disconnect handling
• Ping-timeout reconnection logic refined
• Clean Shutdown() semantics

🌐 WebGL Production Verified

• JavaScript bridge fully tested in production scenarios
• Namespace support validated
• Binary events confirmed working
• Reconnection behavior verified in-browser

🧪 Developer Experience

• Basic Chat Sample added (production-ready onboarding)
• Network HUD moved to top-level SocketIO menu
• Assembly metadata (AssemblyInfo.cs) added

🔄 Upgrading from v0.3.0-alpha

✅ No breaking changes — fully backward compatible

The API surface you've been using is now guaranteed stable through all v1.x releases.

⚠️ Platform Notes

• WebGL: Production verified ✅
• Editor/Desktop: Production ready ✅
• Mobile: Not yet officially certified (community-tested)
• Socket.IO v1/v2: Intentionally unsupported
• Engine.IO polling: Intentionally unsupported

🔗 Links

• Full Changelog
• Documentation: README.md, API_STABILITY.md, DEBUGGING_GUIDE.md