Multiplayer

Experiences in Spatial are multiplayer by default. On top of the existing multiplayer experience, you can introduce your own custom multiplayer behavior.

  • Synced Object Component - A component that can be added to GameObjects that automatically makes them synchronized across all clients. This is easier to use than Space Objects if you have no multiplayer experience. These can be used on GameObjects embedded in a Scene, or in Prefabs.
  • Space Objects - A purely data oriented way to access and sync state across clients. This allows you to access internal Spatial space content types too.
  • Servers & Matchmaking - Learn how to create and manage server instances and use matchmaking in Spatial.
  • Remote Events - Send custom messages to other clients in a space.

Multiplayer features are controlled through the following scripting services:

  • Actor Service - A service that provides access to actors (players) in a server instance.
  • Networking Service - A service to control server instances, get connection status and broadcast custom remote events.
  • Space Content Service - A service that provides access to all objects in a server instance.

Vocabulary

  • Client: A single connected user in a space. But keep in mind some experiences allow a user to join as multiple clients.
  • Actor: Same as a client, these words are used interchangeably.
  • Ownership: Responsibility for certain objects or state in a space.
  • State: Overarching term to describe data like transform positions and custom variables. State can be synced or un-synced depending on the context.
  • Server Instance: A session that connects a group of clients together. Each space may have multiple server instances.
  • Remote Event: A custom message sent to other clients in a server instance. Also commonly referred to as Remote Procedure Calls (RPCs).

Concepts

If you are familiar with Photon Networking in Unity, you will be familiar with these concepts. Largely, the networking architecture in Spatial is similar to Photon Fusion Shared Mode.

Ownership

Each object (SpaceObject or Spatial Synced Object) has a single owner actor. That owner controls the object and it's local state is considered the source of truth.

By default, the creator of an object is the owner, however ownership can be taken over by other actors or transferred if it is permitted.

If a client tries to modify the state of an object they do not own, it will be rejected by the server.

Master Client

A server instance always has a single actor designated as the master client. This can be useful for certain server-like behaviors, for example deciding when to "start" a game or controlling bot behavior.

You can check who is the master client using INetworkingService.isMasterClient or INetworkingService.masterClientActorNumber.

When the master client disconnects, a new master client is automatically chosen by our servers. The INetworkingService.onMasterClientChanged event is triggered when the master client changes.

Synchronized State

In Spatial, clients are synchronized through state updates called operations. This means when a client modifies the position of a synced object or space object, all other clients will receive a message like:

SET scene/transforms/0/position = (100,0,0)
SET scene/transforms/0/position = (100,0,0)

And that operation is applied to the local state for that object.

State changes to an object are applied locally immediately and broadcasted to other clients via the relay server. The Spatial relay server may reject state changes if they are invalid and push back the correct state.

Object Lifecycle

Synchronized objects can be created using these two methods:

When an object is destroyed, it is also destroyed on all clients connected to the server instance.

By default, objects created using the toolkit stay alive until the server instance closes down (which happens when all actors have left and the server instance is empty).

Synced objects have a destroyOnCreatorDisconnect property that can be set, which will destroy the object for all clients when the creator of that object disconnects.

Multiplayer Architecture

All traffic between clients connected to a single server instance of a space is routed through a relay server. This ensures that clients can communicate with each other even if they are behind firewalls or NATs.

Server and clients

Saved content for a space is stored in the Spatial Cloud. A server instance loads the content when it starts and saves it periodically if it is the host instance. Note that there can only be one host instance at a time.

Persistence