Mirror Networking & Discipline

Pure Mirror over KCP, server-authoritative. A short list of discipline rules keeps client-only code out of the dedicated-server build and game-state mutations on the server.

Why Mirror

Mirror is MIT-licensed, battle-tested, and models the server-authoritative design this project needs. Transport is KCP (UDP-based, Mirror's default) โ€” fine for ~10 players on a self-hosted server. No Netcode-for-GameObjects anywhere in the codebase.

Concepts in use

  • NetworkManager โ€” connections, spawning, scenes (subclassed as RodNetworkManager)
  • NetworkIdentity โ€” marks a GameObject as networked
  • [SyncVar] โ€” auto-syncs values (identity, health, wave state) to clients
  • [Command] โ€” client โ†’ server (player casts an ability)
  • [ClientRpc] โ€” server โ†’ all clients (ability VFX, hit confirmation)

Mirror discipline โ€” the non-negotiables

๐Ÿ›‘ The UNITY_SERVER guard trap

Client-only code (VFX, UI, HUD attach) must be guarded with #if UNITY_EDITOR || !UNITY_SERVER โ€” never #if !UNITY_SERVER alone. The editor's active build target is Dedicated Server, so UNITY_SERVER is defined there too; !UNITY_SERVER alone silently strips client code in the editor. The UNITY_EDITOR || prefix keeps it compiled for editor play-mode while still excluding it from real server builds.

  • [Server] on every game-state mutation. Combat core (EnemyController, WaveSpawner, WorldBossController, ArenaSessionController) all gate mutations correctly.
  • Client-side singletons are notified from OnStartClient hooks, not from server-side spawn paths โ€” otherwise you get a host-mode-only bug where clients never get notified in a real client/server split.
  • Spawn networked objects with NetworkServer.Spawn, not plain Instantiate. Ability deployables (mines/walls/zones/turrets) historically used bare Instantiate โ†’ invisible to other players. See Known Issues & Tech Debt and Ability Atlas & Synergies.

Player connect & spawn

  1. Client logs in โ†’ JWT from the auth server; character data (class + saved position) fetched.
  2. RodNetworkAuthenticator verifies the JWT server-side, stores RodPlayerAuth on conn.authenticationData.
  3. Client sends CreatePlayerMessage (username + selected class as fallback).
  4. Server reads auth data, picks the class prefab, determines spawn position, calls NetworkServer.AddPlayerForConnection.

Spawn position resolves in order: (1) saved DB position if non-zero, (2) a scene NetworkStartPosition (8-point ring), (3) random ring scatter at radius 3. First-time logins store (0,0,0), so a zero-check treats all-zero as "no saved position" to avoid everyone stacking inside the ground.

Headless server detection

The dedicated build is IL2CPP/Linux; Unity reports graphicsDeviceType == Null in headless mode. RodNetworkManager.Start() detects this and calls StartServer() automatically โ€” no manual start. Client-only code also short-circuits on this check as a runtime backstop.

โ„น๏ธ Known bandwidth traps

Hero and base-enemy prefabs were missing NetworkTransform (they spawn but freeze for other players) โ€” fixed via the editor step BCE โ–ถ Setup โ–ถ 4n (NetworkSyncFixer.cs). Interest management is handled by SceneDistanceInterestManagement โ€” see Zones, Scenes & Multi-Zone.


Related: Architecture & Topology ยท Login & Authentication Flow ยท Zones, Scenes & Multi-Zone ยท Party System