Architecture & Topology

Two authoritative servers, one client. The Unity/Mirror game server owns real-time state; the Node API owns everything that must persist.

Topology (live)

Unity Client โ”€โ”€KCP/UDP 7777โ”€โ”€โ–บ crossworlds-server (Linux headless, Mirror)
     โ”‚                                   โ”‚
     โ”‚ HTTP REST (JWT)                   โ”‚ REST (server-side verify)
     โ–ผ                                   โ–ผ
crossworlds-auth  :3000  โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–บ MySQL 8 (crossworlds DB)
crossworlds-dashboard :4000 (admin/GM)
rod-realtime      :5000  (Socket.io co-op companion; "RoD" is legacy Rate of Decay naming)
spacetimedb       127.0.0.1:3500 (present; not in the documented client flow)
Nginx :80/443 (playcrossworlds.com, downloads) ยท Uptime Kuma :3001

For the complete verified service/port inventory, bot-side listeners, staging stack, firewall exposure, and current audit findings, see Bot Fleet & VPS Operations.

The authority split

ServerAuthoritative for
crossworlds-server (Unity/Mirror)Real-time state โ€” enemy AI, waves, boss phases, ability effects, deployables, chat, player spawn & position
crossworlds-auth (Node)Persistence โ€” accounts, characters, inventory, progression, crafting, mastery, and kill-reward validation (hit-gate + kill-cooldown)

Unity never touches the database directly. All persistence flows through the REST API. This is why the API contract is load-bearing: a renamed server field silently breaks JsonUtility parsing on the client.

Core systems & where [Server] lives

SystemKey filesAuthority
Networking / sessionRodNetworkManager, RodNetworkAuthenticator, PlayerIdentity, RodPositionSaver, RodChatManagerServer-auth spawn & class; SyncVars for identity
Multi-zoneZoneManager, SceneNames, SceneDistanceInterestManagementServer; additive per-zone scenes
Enemy combatEnemyController (FSM), EnemyProjectile, Health, StatusEffectManagerServer; clients get VFX/health-bar hooks
Waves / bossesWaveSpawner, WaveChest, WorldBossControllerServer coroutine loops; SyncVars for HUD
AbilitiesAbilityCaster + AbilityDef, per-class handlers, deployables, SnapshotSystemMixed โ€” Commands โ†’ server effects
Persistence singletonsInventoryManager, PlayerProgressManager, HeroMasteryManagerClient-initiated REST with JWT
โš ๏ธ Authority gap

The persistence layer is client-initiated REST outside Mirror entirely โ€” so game-state authority effectively bypasses [Server] for anything that persists. Kill rewards are mitigated server-side by /api/combat/kill, but the save-progress path remains value-trusted. See Known Issues & Tech Debt.

Dependency graph โ€” what breaks what

  • Node API response shapes โ†’ the JsonUtility parsers. Any field rename silently breaks parsing.
  • Class index order (0โ€“4) must stay in lock-step across RodNetworkManager.classPrefabs, PlayerIdentity.ClassNames, CharacterSelect, and the server's CLASS_NAMES. Names diverge; the index does not. See Canonical Facts & Doc Divergences.
  • Scene names as strings wire portals and travel โ€” centralized in SceneNames.cs. See Zones, Scenes & Multi-Zone.
  • Old gear endpoints/tables (item_template, character_gearโ€ฆ) are sacred โ€” Unity calls them on every spawn.

Related: Mirror Networking & Discipline ยท Auth & Game API ยท Database Schema ยท Login & Authentication Flow ยท Zones, Scenes & Multi-Zone