Get SpatialOS

Sites

Menu
These are the docs for 13.2, an old version of SpatialOS. 13.3 is the newest →

Load balancing with the new Runtime

This page is only relevant if you haven’t yet upgraded to the new bridge and the new load balancer.

You can configure how each type of worker is scaled and load balanced by picking a strategy for a layer.

You set this configuration for each worker type in the launch configuration file, in the load_balancing field:

"load_balancing": {
    "layer_configurations": [
        {
            "layer": "physics",
            // strategy goes here
        },
        {
            "layer": "chat",
            // strategy goes here
        }
    ]
},

What your approach to load balancing should be

You should regularly be testing your game with more than one managed worker of a type.

This way, your code will be able to handle multiple workers from the start, making it much easier to scale.

Strategies

Rectangular grid (rectangle_grid)

This strategy divides the world up into a rectangular grid of the specified number of rows and columns. There are no overlap regions between the worker authority regions.

When you’d want to use this strategy:

  • For small deployments with just a few workers
  • When you want to know where the boundaries are for testing
  • When you don’t want overlap regions

Example configuration

"load_balancing": {
    "layer_configurations": [
        {
            "layer": "physics",
            "rectangle_grid": {
                "cols": 2,
                "rows": 2
            }
        }
    ]
},

Hexagonal grid (hex_grid)

This strategy tiles the entirety of the game world as a hexagonal grid, and then places a worker with a circular authority region at the centre of each hexagon. This minimizes the surface area between workers.

You specify the number of workers you want to use, and a grid that covers the world will be generated automatically.

When you’d want to use this strategy:

  • Experimenting with worker authority overlap
  • If you want it to be efficient for minimizing migrations between workers

Overlap regions

In this strategy, worker authority regions can overlap with each other.

In an overlap region, it’s valid for either worker to have authority over the appropriate components (the components are not guaranteed to all come over together, though in practice they probably will).

Entity components will generally stay on the worker they’re already on instead of swapping over in the overlap region. This means that authority doesn’t thrash for entities between the two workers.

In the diagram below, you can see that the overlap region can form quite a lot of the world when you use a hexagonal grid configuration with few workers. The black line represents the world boundaries; a hexagonal grid with four workers has been generated to cover that world.

Hexagonal load-balancing showing overlap regions

Example configuration

"load_balancing": {
    "layer_configurations": [
        {
            "layer": "physics",
            "hex_grid": {
                "num_workers": 4
            }
        }
    ]
},

Points of interest (points_of_interest)

In this strategy, you specify key locations in the world that should not be simulated by more than one worker.

You provide a list of “seeds” or points of interest. From those seeds, the world is divided into regions. Each region consists of the area of the world that is closest to the point of interest (similar to a Voronoi diagram using the Manhattan distance).

Once the world has been split into regions, the strategy distributes the regions amongst a specified number of workers.

Example configuration

"load_balancing": {
    "layer_configurations": [
        {
            "layer": "physics",
            "points_of_interest": {
                "num_workers": 2,
                "points": [
                    {
                        "x": 100,
                        "z": 100
                    },
                    {
                        "x": 100,
                        "z": -100
                    },
                    {
                        "x": -100,
                        "z": 100
                    },
                    {
                        "x": -100,
                        "z": -100
                    }
                ]
            }
        }
    ]
}

This configuration specifies four points of interest and two workers. Since there are four points of interest, there are four regions: top left, top right, bottom left and bottom right.

The load balancer distributes the four regions amongst the two workers that are available. It will try to make sure that it picks regions which are adjacent to each other. This minimizes the total area that each worker will have to simulate. In this example, the workers will either split the regions such that both the regions on the left are on one worker and both regions on the right are on the other worker; or split the regions such that both regions on the top are on one worker and both regions on the bottom are on the other worker. The load balancer will not split the regions such that diagonal points are on the same worker.

Don’t start workers

If you don’t want SpatialOS to start any workers of a type, don’t specify a layer for it: leave it out of the configuration file.

When you’d want to use this:

  • Usually, just for client workers

A mixture of strategies

You can also use different strategies for different layers.

Example configuration

"load_balancing": {
    "layer_configurations": [
        {
            "layer": "physics",
            "rectangle_grid": {
                "cols": 2,
                "rows": 2
            }
        },
        {
            "layer": "chat",
            "hex_grid": {
                "num_workers": 4
            }
        },
    ]
},

Options

Manual worker connection

There’s a new feature for debugging: the ability to tell the Runtime not to start any workers manually for a given layer. You can still specify a load-balancing strategy, but you start and connect any ‘managed’ workers yourself.

To do this, set the option manual_worker_connection_only for that layer:

"load_balancing": {
    "layer_configurations": [
        {
            "layer": "physics",
            "hex_grid": {
                "num_workers": 4
            },
            "options": {
                "manual_worker_connection_only": true
            }
        }
    ]
},

Then you can start workers:

In the example above, the configuration specifies four workers to cover the world. So, in order to simulate all of the world, you’d need to manually connect four individual workers.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums