Scope, Idle & Freeze Entities

Photon Bolt has three different methods which lets you control if state updates for a specific entity is sent to remotes or not.
This can be useful if you have a large map and your players just don't need to receive any data from other entities that are far away from it, for example.
These utilities are mainly used to save bandwidth and processing power on the Game Server when only part of your players need to be aware of certain entity updates.

All the following methods are available directly through a BoltEntity and can be set individually, by the entity and by connection in some cases. This giver you the flexibility needed to filter which entities a client will be informed about.

Scoping an Entity

In order to signal to Bolt that an entity need to exist or not on a certain connection, we are talking about the Scope.
It's included on the API of a BoltEntity the method SetScope(BoltConnection connection, bool inScope, bool force), letting you setup exactly that.

When calling this method you pass a connection, a boolean value in for the inScope and an optional force boolean.
If you pass true in, this entity will be created on the other end of the connection, and will receive state updates.
If the entity already exists on the remote end, nothing happens.
If you pass false in, the entity will be completely destroyed on the other end of the connection.
If the entity doesn't exist on the other end, nothing happens when you pass false in.

By default, you can't remove from scope an entity that the connection has control over, raising an error message to signal this.
In the case that you really needs this behavior to happen, it's possible to pass true to the force parameter, removing this barrier.

If you destroy an entity on a remote connection by passing false in, the next time you create it by passing true in all data for this entity has to be re-sent over the wire.
To be able to use SetScope you need to switch Scoping Mode from Automatic to Manual in the Bolt Settings window.
When using the Manual mode of scoping, you must set the scope value for each entity on each connection.

What is an example scenario for using SetScope?

If your players character is being moved to another part of the world which requires a loading screen then entity.SetScope(playerConnection, false) can (and should) be used to destroy all entities that existed in the previous place in the world that the player left.

Idling an Entity

Setting up an Entity as Idle is another technique used to control the update flow.
The method for this is the entity.Idle(BoltConnection connection, bool idle), you pass in a connection and a boolean true/false value.
If you pass in true then you set this entity as idle on the connection passed in, which means that it will stop sending state updates.
If you pass in false you remove the idle state and state updates will flow again.
This has to be done per connection and there is no global idle state that you can set.

What is an example scenario for using Idle?

If you are implementing a type of area of interest functionality and a specific player leaves the area of interest for an entity in the world, setting entity.Idle(playerConnection, true) for the entity will stop any state updates from transferring to the player.

Freeze an Entity

Freeze is the latest method that deals with saving network traffic and CPU.
It is a global setting which can only be activated/de-activated on the owner of an entity.
When you call entity.Freeze(true) what happens is the following:

1. All Bolt Simulate* methods are not invoked any more.
2. No property callbacks be invoked.
3. No state changes will be sent over the network to anyone.

The entity will still exist on everyone that has received a proxy for it, and it will be available for use together with other Bolt functionality such as raising events or setting it as a parameter on another states property, etc.

When you call entity.Freeze(false) the following will happen.

1. Bolt will start calling Simulate* again.
2. All pending property callbacks will be invoked.
3. The changed state will start being replicated to over the network to all remotes.

What is an example scenario for using Freeze?

If you are building an area of interest solution for a big world, while calling Idle for each specific players connection is correct, you might also want to call entity.Freeze(true) when no players at all are near the entity in the world to save CPU resources on the server.