AR-007 — Netcode and hosting topology (LOCKED)

Promoted from Action Required card AR-007. This is the decision of record.

This is probably the most expensive decision in the entire project. If we get this wrong, you could end up rewriting multiplayer 12 months into development. My recommendation is to NOT use Unity NGO the way most tutorials do. Most tutorials use: Player Phone │ ▼ Host Player │ Other Players This is Host Mode. It is completely unsuitable for a competitive battle royale. --- # AR-007 — Netcode & Hosting Topology (LOCKED) Status: APPROVED Priority: CRITICAL --- # Netcode Philosophy Astra is a competitive online multiplayer game. Therefore: > The client is never authoritative. No mobile device is trusted to decide: * Damage * Hits * Position * Ability activation * Barrier placement * Match results The server is the single source of truth. --- # Server Model ## Dedicated Server Every match runs on its own dedicated game server. Players never host matches. There is no peer-to-peer networking. There is no client-host mode. --- # Technology Stack ## Unity Version Unity 6 LTS --- ## Networking Unity Netcode for GameObjects (NGO) Configured for Dedicated Server Mode NOT Host Mode. --- ## Transport Unity Transport Package (UTP) UDP Reliable + Unreliable channels. --- ## Game Server Unity Dedicated Server Build Linux Headless Runs on Contabo VPS. --- # Hosting Topology text Internet │ ┌─────────┴─────────┐ │ │ Unity Authentication ProjectOS │ │ └─────────┬─────────┘ │ Matchmaking │ Allocate Game Server │ Dedicated Server (Contabo) │ ┌────────┬────────┬────────┐ │ │ │ │ Player Player Player Player Only the dedicated server owns the match. --- # Server Authority The dedicated server validates: * Player movement * Position * Rotation * Weapon firing * Hit detection * Damage * Barrier deployment * Ability usage * Circle logic * Loot spawning * Match results * Death * Revive * Inventory Clients request. Server decides. --- # Client Responsibility The client only performs: * Rendering * Input collection * UI * Audio * Prediction * Interpolation * Visual effects Nothing gameplay-critical. --- # Match Lifecycle text Player Login │ ▼ Authentication │ ▼ Queue │ ▼ Matchmaking │ ▼ Dedicated Server Allocated │ ▼ 24 Players Connect │ ▼ Match Starts │ ▼ Match Ends │ ▼ Results Saved │ ▼ Server Shutdown Every match gets a fresh server instance. --- # Dedicated Server Specification Launch Target One match per server process. Supports: * 24 Players * Solo * Duo Designed for: * 60 tick simulation (initial target may be tuned during testing) * Server-authoritative gameplay --- # Matchmaking Handled by Unity Gaming Services. Responsibilities: * Queue management * Region selection * Match creation Once a match is ready: Players are assigned to a dedicated Contabo server. UGS does not run the simulation. --- # Server Regions Launch One region. Nearest to target player base. Future Multiple regional deployments. --- # Prediction Clients use: Client-side prediction for: * Movement * Camera * Animation responsiveness Server remains authoritative. Incorrect predictions are corrected smoothly. --- # Lag Compensation Server stores a short history of player positions. When a shot is fired: Server validates using historical snapshots. This reduces unfair disadvantages caused by latency. --- # Tick Rate Target 30 Hz simulation at launch. Reason: * Suitable for mobile. * Lower bandwidth. * Lower server CPU. * Proven by many mobile shooters. The architecture should allow future testing of higher rates if needed. --- # Synchronization Replicated Objects * Players * Weapons * Barriers * Loot * Projectiles * Zone * Interactive map objects Visual effects are local whenever possible. Only gameplay state is synchronized. --- # Server Persistence The dedicated server stores no permanent player data. After the match: Results are sent to the Aurion Backend. Server instance is destroyed. Persistent progression lives only in PostgreSQL. --- # Security The client is never trusted. The server validates: * Movement speed * Fire rate * Damage * Cooldowns * Inventory * Match rewards * Barrier placement * Ability timing Cheat detection operates on server-side data. --- # Scalability The architecture supports: * Additional server nodes. * Regional deployments. * Automatic scaling. * Load balancing. No gameplay changes required. --- # Development Strategy ## Phase 1 One dedicated server. One VPS. Testing only. --- ## Phase 2 Multiple dedicated servers. Automated deployment. Alpha. --- ## Phase 3 Regional scaling. Production monitoring. Launch. --- # Why Not Host Mode? Host mode is rejected because: * Host has unfair latency advantage. * Host migration complicates gameplay. * Match ends if host disconnects. * Easier to cheat. * Unsuitable for competitive PvP. Astra is designed from day one around dedicated servers. --- # Why Unity Netcode for GameObjects? Current reasons: * Official Unity support. * Strong integration with Unity Dedicated Server. * Good tooling. * Lower development complexity for a solo founder. * Large documentation and community. The networking layer is abstracted so that a future migration remains possible if project requirements significantly change. --- # Future Review Point The networking stack will be re-evaluated after the Vertical Slice. Migration is considered only if: * Performance targets are not met. * Scalability limitations become measurable. * Production profiling demonstrates NGO is the bottleneck. No migration will be considered based on preference alone. --- # 🔒 Final Architecture Decision | Component | Technology | | -------------- | ---------------------------------- | | Engine | Unity 6 LTS | | Multiplayer | Unity Netcode for GameObjects | | Transport | Unity Transport (UDP) | | Hosting | Dedicated Linux Servers on Contabo | | Authority | 100% Server Authoritative | | Matchmaking | Unity Gaming Services | | Authentication | Unity Gaming Services | | Backend | Custom Aurion Backend | | Database | PostgreSQL (Contabo) | | Persistence | Aurion Backend only | --- ## One recommendation I would change from the original plan I would not hard-lock NGO forever. Instead, I would write the architecture as: > "Unity Netcode for GameObjects is the approved networking framework for Version 1.0, provided it continues to meet Astra's performance, scalability, and dedicated-server requirements." Why? Because if Unity introduces a better official solution, or if a mature alternative (such as Photon Fusion or another proven dedicated-server framework) clearly outperforms NGO for your requirements in the future, you want the freedom to evaluate it without violating your own architecture document. That wording keeps the project stable while avoiding an unnecessary long-term technical lock-in.