/// <summary>
/// Updates and synchronizes this Room's Custom Properties. Optionally, expectedProperties can be provided as condition.
/// </summary>
/// <remarks>
/// Custom Properties are a set of string keys and arbitrary values which is synchronized
/// for the players in a Room. They are available when the client enters the room, as
/// they are in the response of OpJoin and OpCreate.
///
/// Custom Properties either relate to the (current) Room or a Player (in that Room).
///
/// Both classes locally cache the current key/values and make them available as
/// property: CustomProperties. This is provided only to read them.
/// You must use the method SetCustomProperties to set/modify them.
///
/// Any client can set any Custom Properties anytime (when in a room).
/// It's up to the game logic to organize how they are best used.
///
/// You should call SetCustomProperties only with key/values that are new or changed. This reduces
/// traffic and performance.
///
/// Unless you define some expectedProperties, setting key/values is always permitted.
/// In this case, the property-setting client will not receive the new values from the server but
/// instead update its local cache in SetCustomProperties.
///
/// If you define expectedProperties, the server will skip updates if the server property-cache
/// does not contain all expectedProperties with the same values.
/// In this case, the property-setting client will get an update from the server and update it's
/// cached key/values at about the same time as everyone else.
///
/// The benefit of using expectedProperties can be only one client successfully sets a key from
/// one known value to another.
/// As example: Store who owns an item in a Custom Property "ownedBy". It's 0 initally.
/// When multiple players reach the item, they all attempt to change "ownedBy" from 0 to their
/// actorNumber. If you use expectedProperties {"ownedBy", 0} as condition, the first player to
/// take the item will have it (and the others fail to set the ownership).
///
/// Properties get saved with the game state for Turnbased games (which use IsPersistent = true).
/// </remarks>
/// <param name="propertiesToSet">Hashtable of Custom Properties that changes.</param>
/// <param name="expectedProperties">Provide some keys/values to use as condition for setting the new values. Client must be in room.</param>
/// <param name="webFlags">Defines if this SetCustomProperties-operation gets forwarded to your WebHooks. Client must be in room.</param>
/// <returns>
/// False if propertiesToSet is null or empty or have zero string keys.
/// True in offline mode even if expectedProperties or webFlags are used.
/// Otherwise, returns if this operation could be sent to the server.
/// </returns>
public virtual bool SetCustomProperties(Hashtable propertiesToSet, Hashtable expectedProperties = null,
WebFlags webFlags = null)
{
if (propertiesToSet == null || propertiesToSet.Count == 0)
{
return(false);
}
Hashtable customProps = propertiesToSet.StripToStringKeys() as Hashtable;
if (this.isOffline)
{
if (customProps.Count == 0)
{
return(false);
}
// Merge and delete values.
this.CustomProperties.Merge(customProps);
this.CustomProperties.StripKeysWithNullValues();
// invoking callbacks
this.LoadBalancingClient.InRoomCallbackTargets.OnRoomPropertiesUpdate(propertiesToSet);
}
else
{
// send (sync) these new values if in online room
return(this.LoadBalancingClient.OpSetPropertiesOfRoom(customProps, expectedProperties, webFlags));
}
return(true);
}
/// <summary>
/// Updates and synchronizes this Player's Custom Properties. Optionally, expectedProperties can be provided as condition.
/// </summary>
/// <remarks>
/// Custom Properties are a set of string keys and arbitrary values which is synchronized
/// for the players in a Room. They are available when the client enters the room, as
/// they are in the response of OpJoin and OpCreate.
///
/// Custom Properties either relate to the (current) Room or a Player (in that Room).
///
/// Both classes locally cache the current key/values and make them available as
/// property: CustomProperties. This is provided only to read them.
/// You must use the method SetCustomProperties to set/modify them.
///
/// Any client can set any Custom Properties anytime (when in a room).
/// It's up to the game logic to organize how they are best used.
///
/// You should call SetCustomProperties only with key/values that are new or changed. This reduces
/// traffic and performance.
///
/// Unless you define some expectedProperties, setting key/values is always permitted.
/// In this case, the property-setting client will not receive the new values from the server but
/// instead update its local cache in SetCustomProperties.
///
/// If you define expectedProperties, the server will skip updates if the server property-cache
/// does not contain all expectedProperties with the same values.
/// In this case, the property-setting client will get an update from the server and update it's
/// cached key/values at about the same time as everyone else.
///
/// The benefit of using expectedProperties can be only one client successfully sets a key from
/// one known value to another.
/// As example: Store who owns an item in a Custom Property "ownedBy". It's 0 initally.
/// When multiple players reach the item, they all attempt to change "ownedBy" from 0 to their
/// actorNumber. If you use expectedProperties {"ownedBy", 0} as condition, the first player to
/// take the item will have it (and the others fail to set the ownership).
///
/// Properties get saved with the game state for Turnbased games (which use IsPersistent = true).
/// </remarks>
/// <param name="propertiesToSet">Hashtable of Custom Properties to be set. </param>
/// <param name="expectedValues">If non-null, these are the property-values the server will check as condition for this update.</param>
/// <param name="webFlags">Defines if this SetCustomProperties-operation gets forwarded to your WebHooks. Client must be in room.</param>
/// <returns>
/// False if propertiesToSet is null or empty or have zero string keys.
/// True in offline mode even if expectedProperties or webFlags are used.
/// If not in a room, returns true if local player and expectedValues and webFlags are null.
/// (Use this to cache properties to be sent when joining a room).
/// Otherwise, returns if this operation could be sent to the server.
/// </returns>
public bool SetCustomProperties(Hashtable propertiesToSet, Hashtable expectedValues = null,
WebFlags webFlags = null)
{
if (propertiesToSet == null || propertiesToSet.Count == 0)
{
return(false);
}
Hashtable customProps = propertiesToSet.StripToStringKeys() as Hashtable;
if (this.RoomReference != null)
{
if (this.RoomReference.IsOffline)
{
if (customProps.Count == 0)
{
return(false);
}
this.CustomProperties.Merge(customProps);
this.CustomProperties.StripKeysWithNullValues();
// invoking callbacks
this.RoomReference.LoadBalancingClient.InRoomCallbackTargets.OnPlayerPropertiesUpdate(this,
customProps);
return(true);
}
else
{
Hashtable customPropsToCheck = expectedValues.StripToStringKeys() as Hashtable;
// send (sync) these new values if in online room
return(this.RoomReference.LoadBalancingClient.OpSetPropertiesOfActor(this.actorNumber, customProps,
customPropsToCheck, webFlags));
}
}
if (this.IsLocal)
{
if (customProps.Count == 0)
{
return(false);
}
if (expectedValues == null && webFlags == null)
{
this.CustomProperties.Merge(customProps);
this.CustomProperties.StripKeysWithNullValues();
return(true);
}
}
return(false);
}
/// <summary>
/// Updates and synchronizes this Player's Custom Properties. Optionally, expectedProperties can be provided as condition.
/// </summary>
/// <remarks>
/// Custom Properties are a set of string keys and arbitrary values which is synchronized
/// for the players in a Room. They are available when the client enters the room, as
/// they are in the response of OpJoin and OpCreate.
///
/// Custom Properties either relate to the (current) Room or a Player (in that Room).
///
/// Both classes locally cache the current key/values and make them available as
/// property: CustomProperties. This is provided only to read them.
/// You must use the method SetCustomProperties to set/modify them.
///
/// Any client can set any Custom Properties anytime (when in a room).
/// It's up to the game logic to organize how they are best used.
///
/// You should call SetCustomProperties only with key/values that are new or changed. This reduces
/// traffic and performance.
///
/// Unless you define some expectedProperties, setting key/values is always permitted.
/// In this case, the property-setting client will not receive the new values from the server but
/// instead update its local cache in SetCustomProperties.
///
/// If you define expectedProperties, the server will skip updates if the server property-cache
/// does not contain all expectedProperties with the same values.
/// In this case, the property-setting client will get an update from the server and update it's
/// cached key/values at about the same time as everyone else.
///
/// The benefit of using expectedProperties can be only one client successfully sets a key from
/// one known value to another.
/// As example: Store who owns an item in a Custom Property "ownedBy". It's 0 initally.
/// When multiple players reach the item, they all attempt to change "ownedBy" from 0 to their
/// actorNumber. If you use expectedProperties {"ownedBy", 0} as condition, the first player to
/// take the item will have it (and the others fail to set the ownership).
///
/// Properties get saved with the game state for Turnbased games (which use IsPersistent = true).
/// </remarks>
/// <param name="propertiesToSet">Hashtable of Custom Properties to be set. </param>
/// <param name="expectedValues">If non-null, these are the property-values the server will check as condition for this update.</param>
/// <param name="webFlags">Defines if this SetCustomProperties-operation gets forwarded to your WebHooks. Client must be in room.</param>
public void SetCustomProperties(Hashtable propertiesToSet, Hashtable expectedValues = null, WebFlags webFlags = null)
{
if (propertiesToSet == null)
{
return;
}
Hashtable customProps = propertiesToSet.StripToStringKeys() as Hashtable;
Hashtable customPropsToCheck = expectedValues.StripToStringKeys() as Hashtable;
// no expected values -> set and callback
bool noCas = customPropsToCheck == null || customPropsToCheck.Count == 0;
if (noCas)
{
this.CustomProperties.Merge(customProps);
this.CustomProperties.StripKeysWithNullValues();
}
if (this.RoomReference != null)
{
if (this.RoomReference.IsOffline)
{
// invoking callbacks
this.RoomReference.LoadBalancingClient.InRoomCallbackTargets.OnPlayerPropertiesUpdate(this, customProps);
}
else
{
// send (sync) these new values if in online room
this.RoomReference.LoadBalancingClient.LoadBalancingPeer.OpSetPropertiesOfActor(this.actorNumber, customProps, customPropsToCheck, webFlags);
}
}
}
/// <summary>
/// Updates and synchronizes this Room's Custom Properties. Optionally, expectedProperties can be provided as condition.
/// </summary>
/// <remarks>
/// Custom Properties are a set of string keys and arbitrary values which is synchronized
/// for the players in a Room. They are available when the client enters the room, as
/// they are in the response of OpJoin and OpCreate.
///
/// Custom Properties either relate to the (current) Room or a Player (in that Room).
///
/// Both classes locally cache the current key/values and make them available as
/// property: CustomProperties. This is provided only to read them.
/// You must use the method SetCustomProperties to set/modify them.
///
/// Any client can set any Custom Properties anytime (when in a room).
/// It's up to the game logic to organize how they are best used.
///
/// You should call SetCustomProperties only with key/values that are new or changed. This reduces
/// traffic and performance.
///
/// Unless you define some expectedProperties, setting key/values is always permitted.
/// In this case, the property-setting client will not receive the new values from the server but
/// instead update its local cache in SetCustomProperties.
///
/// If you define expectedProperties, the server will skip updates if the server property-cache
/// does not contain all expectedProperties with the same values.
/// In this case, the property-setting client will get an update from the server and update it's
/// cached key/values at about the same time as everyone else.
///
/// The benefit of using expectedProperties can be only one client successfully sets a key from
/// one known value to another.
/// As example: Store who owns an item in a Custom Property "ownedBy". It's 0 initally.
/// When multiple players reach the item, they all attempt to change "ownedBy" from 0 to their
/// actorNumber. If you use expectedProperties {"ownedBy", 0} as condition, the first player to
/// take the item will have it (and the others fail to set the ownership).
///
/// Properties get saved with the game state for Turnbased games (which use IsPersistent = true).
/// </remarks>
/// <param name="propertiesToSet">Hashtable of Custom Properties that changes.</param>
/// <param name="expectedProperties">Provide some keys/values to use as condition for setting the new values. Client must be in room.</param>
/// <param name="webFlags">Defines if this SetCustomProperties-operation gets forwarded to your WebHooks. Client must be in room.</param>
public virtual void SetCustomProperties(Hashtable propertiesToSet, Hashtable expectedProperties = null, WebFlags webFlags = null)
{
Hashtable customProps = propertiesToSet.StripToStringKeys() as Hashtable;
if (this.isOffline)
{
// Merge and delete values.
this.CustomProperties.Merge(customProps);
this.CustomProperties.StripKeysWithNullValues();
// invoking callbacks
this.LoadBalancingClient.InRoomCallbackTargets.OnRoomPropertiesUpdate(propertiesToSet);
}
else
{
// merge (and delete null-values), unless we use CAS (expected props)
if (expectedProperties == null || expectedProperties.Count == 0)
{
this.CustomProperties.Merge(customProps);
this.CustomProperties.StripKeysWithNullValues();
}
// send (sync) these new values if in online room
this.LoadBalancingClient.LoadBalancingPeer.OpSetPropertiesOfRoom(customProps, expectedProperties, webFlags);
}
}
