Host delegation

When connecting to a scene, clients join a star topology with an host and the connected clients. The host is authoritative on the scene and performs “server” operations. The routing layer of the grid is able to locate hosts and route messages to them. By default, scene hosts are started in the grid sandboxes.

However, it’s possible to delegate the host role to a remote peer. By doing this, an host instruct the grid to route all connection requests and messages directed to the scene host to the peer, making it the new host of the scene.

The original host running in the sandbox won’t receive messages, RPCs or execute custom events as long as the role is delegated.

Delegation ends when the remote peer disconnects. When this happens, clients are disconnected from the scene. Any new connections is then directed to the original host and delegation to a new peer is again possible.

As a new host may have different metadata and routes, clients already connected to a scene when the role is delegated are disconnected (with the obvious omission of the new host itself).

Note

It’s not possible to delegate only a part of the API surface of a scene host.

Why Delegating the host role?

Delegating the host authority enable clients to forward requests and messages to another client much like with P2P connections with a notable difference:

  • P2P connections are direct between 2 clients.

  • When Host delegation happens, messages to the new host are still routed through the grid routing layer, allowing complex routing scenarios.

When a scene is sharded (distributed between a set of scene hosts), the host of each scene shard handles a part of the total load supported by the scene. Using delegation in this scenario allows the load to be supported by a C++ client for instance.

For instance, when using spatial sharding to create a seamless world, using delegation enables an Unreal4 or Unity3D game engine to host parts of the worlds, while messages and entity replication is orchestrated transparently by the grid.

Delegating the host role

C# Server Application

When a scene is started, the host is always instantiated as a C# scene hosted by the grid. The scene custom code can call Task ISceneHost.DelegateHost(string sessionId) during scene initialization to choose a new give host authority to a peer connected to the server application

string sessionId;
await scene.DelegateHost(sessionId);

Note

Once delegation is given to a client, disconnecting it from the scene is the only way to cancel it.

Client code

When host authority for a scene shard is delegated to a client, it initializes and starts a scene host on it. To enable that, a client must register a scene builder callback associated with the scene template of the server:

client->addBuilder(SCENE_TEMPLATE,[](std::shared_ptr<IScene> scene){
    scene->addRoute(...);
    ...

});

The newly created scene has the same behavior as a C# server scene, and supports the same extensibility points exposed in the IHostPlugin interface