기술 자료

Multiplayer Services SDK

All Services

Multiplayer Services SDK

Manage properties as a host

Manage your sessions with the operations available to you as a session host.
읽는 시간 4분최근 업데이트: 14일 전
As a session host, you have access to operations that let you interact with session and player properties.
Note that some host operations differ from those available to clients.

Session property operations

The host can read, add, update, or remove properties from a session.

Read APIs

The following APIs allow the host to read session properties:
IReadOnlyDictionary<string, SessionProperty> ISession.Properties { get; }

Read a session property

The following code snippet demonstrates how to read the 
colour
property:
if (clientSession.Properties.TryGetValue("colour", out var colour)){    Debug.Log($"The colour session property is {colour.Value}");}

Write APIs

The following APIs allow the host to modify session properties:
void IHostSession.SetProperties(Dictionary<string, SessionProperty> properties);void IHostSession.SetProperty(string key, SessionProperty property);Task IHostSession.SavePropertiesAsync();

Add a session property

To add a property to a session, you must decide upon the visibility of the property:
  • Public (visible to everyone and is included in query result)
  • Member (visible to members of the session)
  • Private (visible to the member who set it)
After you decide the required visibility, you must create the session property, set it, and save it to the session. The following code snippet demonstrates how to add a 
colour
property with the value 
red
in 
hostSession
:
var redColourProperty = new SessionProperty("red", VisibilityOptions.Public);hostSession.SetProperty("colour", redColourProperty);await hostSession.SavePropertiesAsync();

Add an indexed session property

To make a public session property queryable, assign it a 
PropertyIndex
. The 
SessionProperty
constructor accepts an optional 
index
parameter that maps the property to a reserved slot: 
String1
through 
String5
for string values, and 
Number1
through 
Number5
for numeric values. Properties default to 
PropertyIndex.None
, which means they're not queryable even when their visibility is 
Public
.
The following code snippet demonstrates how to add a 
gameMode
property indexed under 
String1
:
var gameModeProperty = new SessionProperty("CaptureTheFlag", VisibilityOptions.Public, PropertyIndex.String1);hostSession.SetProperty("gameMode", gameModeProperty);await hostSession.SavePropertiesAsync();
Clients can then filter for this property using 
FilterField.StringIndex1
in 
QuerySessionsOptions
. Refer to Query sessions by custom properties for the client-side query example.
참고
Each session supports a maximum of 5 indexed string properties and 5 indexed numeric properties, out of 20 properties total. Indexed properties are limited to 128 B each, compared to 2 KB for non-indexed properties.
Because a query filters by index slot rather than by property name, avoid assigning the same 
PropertyIndex
to properties that mean different things across sessions. Doing so won't raise an error, but it will produce unpredictable results for clients querying on that index.

Update a session property

The following code snippet demonstrates how to set the 
colour
property to 
null
in 
hostSession
.
var nullSessionProperty = new SessionProperty(null, VisibilityOptions.Public);hostSession.SetProperty("colour", nullSessionProperty);await hostSession.SavePropertiesAsync();
참고
Updating a property preserves its existing 
PropertyIndex
unless you explicitly set a different one. To change or remove which index slot a property uses, pass the new 
PropertyIndex
value (or 
PropertyIndex.None
) when constructing the replacement 
SessionProperty
.

Delete a session property

The following code snippet demonstrates how to delete the 
colour
property in 
hostSession
.
hostSession.SetProperty("colour", null);await hostSession.SavePropertiesAsync();

Player property operations

The host can read, add, update, or remove properties from any player.

Read APIs

The following APIs allow the host to read player properties:
IReadOnlyList<IPlayer> IHostSession.Players { get; }IReadOnlyDictionary<string, PlayerProperty> IReadOnlyPlayer.Properties { get; }

Read a player property

The following code snippet demonstrates how to read the 
colour
player property.
if (hostSession.Players.First().Properties.TryGetValue("colour", out var colour)){    Debug.Log($"First player colour property is {colour.Value}");}

Write APIs

The following APIs allow the host to modify player properties:
IReadOnlyList<IPlayer> IHostSession.Players { get; }Task IHostSession.SavePlayerDataAsync(string playerId);void IPlayer.SetProperty(string key, PlayerProperty property);void IPlayer.SetProperties(Dictionary<string, PlayerProperty> properties);

Add a player property

To add a property to a player, you must decide upon the visibility of the property:
  • Public (visible to everyone)
  • Member (visible to members of the session)
  • Private (visible to the player who owns the property and the host)
The following code snippet demonstrates how to add a 
colour
property with the value 
red
in 
firstPlayer
, which is the first client in the list of clients:
var firstPlayer = hostSession.Players.First()var redColourProperty = new PlayerProperty("red");firstPlayer.SetProperty("colour", redColourProperty);await hostSession.SavePlayerDataAsync(firstPlayer.Id);

Update a player property

The following code snippet demonstrates how to set the 
colour
property to 
null
in 
firstPlayer
:
var firstPlayer = hostSession.Players.First()var nullColourProperty = new PlayerProperty(null);firstPlayer.SetProperty("colour", nullColourProperty);await hostSession.SavePlayerDataAsync(firstPlayer.Id);

Delete a player property

The following code snippet demonstrates how to delete the 
colour
property in 
firstPlayer
:
var firstPlayer = hostSession.Players.First()firstPlayer.SetProperty("colour", null);await hostSession.SavePlayerDataAsync(firstPlayer.Id);

Elect a new session host

The following code snippet demonstrates how to elect a given 
player
by its ID as the new host:
public Task ElectPlayerAsHostAsync(string playerId){    _session.AsHost().Host = player.Id;    return _session.AsHost().SavePropertiesAsync();}
After setting the 
session
's host ID, save the changes to take effect.
참고
The host election process doesn't handle the data migration of the network session, it only chooses a new session host. For the network data migration, refer to Session migration.