Entity Initialization Order

Entity initialization has been changed so that the initialization of different kinds of entities now happens in parallel. In most cases, this is the desired behavior and no changes are needed to the game-specific entity configuration.

If you have entities that must be initialized before everything else on the cluster, the newly introduced EntityConfigBase.EntityShardGroup allows configuring the entity initialization order. See Custom Server Entities for details on how to configure the initialization order.

Entity Sharding Strategies

The old classes implementing IShardingStrategy have been renamed to better reflect their behavior and a ShardingStrategies helper has been introduced to make it easier to work with the strategies. Replace your existing usage with the following:

[EntityConfig]
internal sealed class MyEntityConfig : PersistedEntityConfig
{
  // Global singleton services:
  public override IShardingStrategy ShardingStrategy => new ServiceShardingStrategy(numServiceShards: 1);
  // replace with
  public override IShardingStrategy ShardingStrategy => ShardingStrategies.CreateSingletonService();

  // Services with multiple entities:
  public override IShardingStrategy ShardingStrategy => new ServiceShardingStrategy(EntityKind);
  // replace with
  public override IShardingStrategy ShardingStrategy => ShardingStrategies.CreateService();

  // Statically sharded payload entities:
  public override IShardingStrategy ShardingStrategy => new HashedShardingStrategy(Application.Instance.ClusterConfig, EntityKind);
  // replace with
  public override IShardingStrategy ShardingStrategy => ShardingStrategies.CreateStaticSharded();

  // Entities with manually specified EntityIds:
  public override IShardingStrategy ShardingStrategy => new StaticShardingStrategy();
  // replace with
  public override IShardingStrategy ShardingStrategy => ShardingStrategies.CreateManual();
}

For more details, check out Custom Server Entities.

Cluster Topology Configuration

The entities now have a default placement on either the logic or the service NodeSet in the cluster.

From within Options.<env>.yaml, remove the following Clustering options: CommonEntityKinds, TopologyId, and ShardingTopologies.

If the game uses a clustering topology that doesn't match the default service/logic, then check out Configuring Cluster Topology for details on how to customize the clustering topology.

Entity Cluster Placement

Related to the cluster topology configuration changes, game-specific entities must now specify their default placement in the cluster. The entity placements can be overridden using the runtime options.

Depending on the entity, you have three options for the placement:

• NodeSetPlacement.Service should be used for singleton entities where only one copy of the entity exists and other service-style entities that don't need to scale across the cluster.
• NodeSetPlacement.Logic should be used for entities that need to scale across multiple cluster nodes.
• NodeSetPlacement.All should be used for entities that need to be located on all nodes in the cluster. These are usually various daemon-style service entities.

[EntityConfig]
internal sealed class MyEntityConfig : PersistedEntityConfig
{
  // For singleton/service entities, use:
  public override NodeSetPlacement NodeSetPlacement => NodeSetPlacement.Service;

  // For scalable logic entities, use:
  public override NodeSetPlacement NodeSetPlacement => NodeSetPlacement.Logic;

  // For entities that need to be placed on all cluster nodes, use:
  public override NodeSetPlacement NodeSetPlacement => NodeSetPlacement.All;
}

For more details on configuring the entities, check out Custom Server Entities. For information on overriding the entity placements using runtime options and adopting non-default cluster topologies, see Configuring Cluster Topology.