Seamless worlds

Configuring a scene for spatial sharding

When creating or updating a persistent scene, it’s possible to specify a shards parameter that makes the scene distributed. A distributed scene is partitioned as a set of shards that can run on different nodes of the server farm.

Different partitioning policies are available. The implementation of seamless scalable worlds in Stormancer uses the spatial partitioning policy to split a scene into shards that each manages a region of the world.

When configuring the partitioning policy, you must specify a set of regions of interest. A shard is going to be created for each region.

"sharding":{
    "type":"spatial",
    "shards":[
        {
            shape:{
                "type":"box",
                "x":0,
                "y":0,
                "z":0,
                "xWidth":100,
                "yWidth":100,
                "zWidth":100
            }
        },
        {
            shape:{
                "type":"box",
                "x":100,
                "y":0,
                "z":0,
                "xWidth":100,
                "yWidth":100,
                "zWidth":100
            }
        }
    ]

}

Declaring views

Updating player views on the server

//Move the player in the world, it may change the shard it's connected to.
peer.UpdatePartitionKey(new SpatialPartitionKey(x,y,z));

//Update player views
peer.UpdateViews(new Dictionary<string,View>({
        {"near",new Spatial{ shape = new Sphere(x,y,z,100)}},
        {"far",new Spatial{ shape = new Sphere(x,y,z,200)}}
    }));

Scene shards must receive spatialy filtered packets, for instance to enable players and NPC to interact accross shard boundaries. To do that, it’s possible to add views to the shard itself:

scene.UpdateViews(new Dictionary<string,View>({
        {"shard",new Spatial{ shape = new Box(x,y,z,120,120,120)}},
    }));

Sending packets with spatial filtering

When a scene shard needs to send a message to all players/shards that monitor a given area, it can use the SpatialFilter filter to let the distributed filter route the message to peers having a view that intersects the position specified in the filter. The filter also specifies a list of view ids to match.

scene.Send(new SpatialFilter(x,y,z,"near","shard"), data);

Remark: a message may bounce back to the shard it originated from if the shard has a view that matches the filter position.

Using the shard area

Each shard is dedicated to an area as part of the partitioning configuration. Details about this area is available from inside the shard logic, for instance to load and manage NPCs or game entities present in the shard areas.

var shape = scene.GetShardInfos<SpatialShard>().Shape;

The shard shape is available for spatial filtering using the id “_default” to send messages to a shard identified by its area.

scene.Send(new SpatialFilter(x,y,z,"_default"), data);