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
| Server | Authoritative 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
| System | Key files | Authority |
|---|---|---|
| Networking / session | RodNetworkManager, RodNetworkAuthenticator, PlayerIdentity, RodPositionSaver, RodChatManager | Server-auth spawn & class; SyncVars for identity |
| Multi-zone | ZoneManager, SceneNames, SceneDistanceInterestManagement | Server; additive per-zone scenes |
| Enemy combat | EnemyController (FSM), EnemyProjectile, Health, StatusEffectManager | Server; clients get VFX/health-bar hooks |
| Waves / bosses | WaveSpawner, WaveChest, WorldBossController | Server coroutine loops; SyncVars for HUD |
| Abilities | AbilityCaster + AbilityDef, per-class handlers, deployables, SnapshotSystem | Mixed โ Commands โ server effects |
| Persistence singletons | InventoryManager, PlayerProgressManager, HeroMasteryManager | Client-initiated REST with JWT |
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
JsonUtilityparsers. 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'sCLASS_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