Core components
Networking & multiplayer infra...
Instanceserver architecture
9 min
in this chapter, we'll dive into the architecture of the instanceserver, which is the backbone of ir engine's multiplayer capabilities what is an instanceserver? in the world of multiplayer games and virtual worlds, an instanceserver is a dedicated server that hosts a specific instance of a virtual environment think of it as a single "room" or "world" where multiple users can connect and interact with each other in real time in ir engine, the instanceserver is a specialized application that hosts a specific location or scene manages connections from multiple clients synchronizes state between all connected users handles physics simulations processes voice and video communication authenticates users and manages sessions instanceserver package structure the instanceserver is implemented in the @ir engine/instanceserver package let's look at its main components packages/instanceserver/ ├── src/ │ ├── index ts # entry point │ ├── start ts # server startup logic │ ├── instanceserverstate ts # state management │ ├── channels ts # communication channels │ ├── networkfunctions ts # network handling │ ├── socketfunctions ts # socket management │ ├── socketwebrtcserverfunctions ts # webrtc implementation │ └── restartinstanceserver ts # server restart logic └── package json how the instanceserver works when a user wants to join a virtual world in ir engine, the following sequence occurs the client requests to join a specific location the server core provisions an instanceserver (or assigns an existing one) the instanceserver initializes the scene and spatial engine the client connects to the instanceserver via webrtc the instanceserver authenticates the user the client joins the virtual world and begins receiving state updates let's look at the initialization process in more detail // simplified from packages/instanceserver/src/start ts export const start = async () promise\<application> => { // create the feathers application const app = await createfeatherskoaapp(servermode instance, instanceserverpipe) // initialize the spatial timer for physics and animations starttimer() // connect to agones for kubernetes orchestration const agonessdk = new agonessdk() agonessdk connect() agonessdk ready() // set up health checks setinterval(() => agonessdk health(), 1000) // configure communication channels app configure(channels) // initialize the network initializenetwork() return app } instanceserverstate the instanceserver maintains its state using hyperflux, ir engine's state management system the instanceserverstate contains information about the current instance id the location being hosted connected users network status server configuration // simplified from packages/instanceserver/src/instanceserverstate ts export const instanceserverstate = definestate({ name 'instanceserverstate', initial { instance null as instancetype, currentscene null as scenedata, channelid null as channelid, channeltype null as channeltype, videoenabled false, instanceprovisioned false, instanceprovisionid null as instanceprovisionid } }) integration with the engine the instanceserver integrates deeply with ir engine's core systems ecs (entity component system) the instanceserver uses the same ecs architecture as the client, allowing for seamless state synchronization spatial engine the instanceserver runs the spatial engine to handle physics, transformations, and other spatial operations network the instanceserver implements network protocols for efficient state synchronization hyperflux state management is handled through hyperflux, allowing for reactive updates scaling with kubernetes and agones one of the most powerful aspects of the instanceserver architecture is its ability to scale dynamically using kubernetes and agones kubernetes provides the container orchestration platform agones extends kubernetes with game server specific features the instanceserver registers with agones on startup agones manages the lifecycle of instanceserver pods new instances can be provisioned on demand this architecture allows ir engine to scale from a few users to thousands, with each instanceserver handling a specific location or scene conclusion the instanceserver is the foundation of ir engine's multiplayer capabilities it provides a robust, scalable platform for hosting virtual worlds and enabling real time interactions between users in the next chapter, we'll explore how webrtc networking enables low latency communication between clients and the instanceserver