Photon Unity Networking 2: Player Class Reference

Photon Unity Networking 2

Summarizes a "player" within a room, identified (in that room) by ID (or "actorNumber"). More...

Public Member Functions

Player Get (int id)
 Get a Player by ActorNumber (Player.ID). More...
 
Player GetNext ()
 Gets this Player's next Player, as sorted by ActorNumber (Player.ID). Wraps around. More...
 
Player GetNextFor (Player currentPlayer)
 Gets a Player's next Player, as sorted by ActorNumber (Player.ID). Wraps around. More...
 
Player GetNextFor (int currentPlayerId)
 Gets a Player's next Player, as sorted by ActorNumber (Player.ID). Wraps around. More...
 
virtual void InternalCacheProperties (Hashtable properties)
 Caches properties for new Players or when updates of remote players are received. Use SetCustomProperties() for a synced update. More...
 
override string ToString ()
 Brief summary string of the Player. Includes name or player.ID and if it's the Master Client. More...
 
string ToStringFull ()
 String summary of the Player: player.ID, name and all custom properties of this user. More...
 
override bool Equals (object p)
 If players are equal (by GetHasCode, which returns this.ID). More...
 
override int GetHashCode ()
 Accompanies Equals, using the ID (actorNumber) as HashCode to return. More...
 
void SetCustomProperties (Hashtable propertiesToSet, Hashtable expectedValues=null, WebFlags webFlags=null)
 Updates and synchronizes this Player's Custom Properties. Optionally, expectedProperties can be provided as condition. More...
 

Public Attributes

readonly bool IsLocal
 Only one player is controlled by each client. Others are not local. More...
 
object TagObject
 Can be used to store a reference that's useful to know "by player". More...
 

Properties

int ActorNumber [get]
 Identifier of this player in current room. Also known as: actorNumber or actorNumber. It's -1 outside of rooms. More...
 
string NickName [get, set]
 Non-unique nickname of this player. Synced automatically in a room. More...
 
string UserId [get, set]
 UserId of the player, available when the room got created with RoomOptions.PublishUserId = true. More...
 
bool IsMasterClient [get]
 True if this player is the Master Client of the current room. More...
 
bool IsInactive [get, set]
 If this player is active in the room (and getting events which are currently being sent). More...
 
Hashtable CustomProperties [get, set]
 Read-only cache for custom properties of player. Set via Player.SetCustomProperties. More...
 

Detailed Description

Summarizes a "player" within a room, identified (in that room) by ID (or "actorNumber").

Each player has a actorNumber, valid for that room. It's -1 until assigned by server (and client logic).

Member Function Documentation

override bool Equals ( object  p)

If players are equal (by GetHasCode, which returns this.ID).

Player Get ( int  id)

Get a Player by ActorNumber (Player.ID).

Parameters
idActorNumber of the a player in this room.
Returns
Player or null.
override int GetHashCode ( )

Accompanies Equals, using the ID (actorNumber) as HashCode to return.

Player GetNext ( )

Gets this Player's next Player, as sorted by ActorNumber (Player.ID). Wraps around.

Returns
Player or null.
Player GetNextFor ( Player  currentPlayer)

Gets a Player's next Player, as sorted by ActorNumber (Player.ID). Wraps around.

Useful when you pass something to the next player. For example: passing the turn to the next player.

Parameters
currentPlayerThe Player for which the next is being needed.
Returns
Player or null.
Player GetNextFor ( int  currentPlayerId)

Gets a Player's next Player, as sorted by ActorNumber (Player.ID). Wraps around.

Useful when you pass something to the next player. For example: passing the turn to the next player.

Parameters
currentPlayerIdThe ActorNumber (Player.ID) for which the next is being needed.
Returns
Player or null.
virtual void InternalCacheProperties ( Hashtable  properties)
virtual

Caches properties for new Players or when updates of remote players are received. Use SetCustomProperties() for a synced update.

This only updates the CustomProperties and doesn't send them to the server. Mostly used when creating new remote players, where the server sends their properties.

void SetCustomProperties ( Hashtable  propertiesToSet,
Hashtable  expectedValues = null,
WebFlags  webFlags = null 
)

Updates and synchronizes this Player's Custom Properties. Optionally, expectedProperties can be provided as condition.

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).

Parameters
propertiesToSetHashtable of Custom Properties to be set.
expectedValuesIf non-null, these are the property-values the server will check as condition for this update.
webFlagsDefines if this SetCustomProperties-operation gets forwarded to your WebHooks. Client must be in room.
override string ToString ( )

Brief summary string of the Player. Includes name or player.ID and if it's the Master Client.

string ToStringFull ( )

String summary of the Player: player.ID, name and all custom properties of this user.

Use with care and not every frame! Converts the customProperties to a String on every single call.

Member Data Documentation

readonly bool IsLocal

Only one player is controlled by each client. Others are not local.

object TagObject

Can be used to store a reference that's useful to know "by player".

Example: Set a player's character as Tag by assigning the GameObject on Instantiate.

Property Documentation

int ActorNumber
get

Identifier of this player in current room. Also known as: actorNumber or actorNumber. It's -1 outside of rooms.

The ID is assigned per room and only valid in that context. It will change even on leave and re-join. IDs are never re-used per room.

Hashtable CustomProperties
getset

Read-only cache for custom properties of player. Set via Player.SetCustomProperties.

Don't modify the content of this Hashtable. Use SetCustomProperties and the properties of this class to modify values. When you use those, the client will sync values with the server.

SetCustomProperties

bool IsInactive
getset

If this player is active in the room (and getting events which are currently being sent).

Inactive players keep their spot in a room but otherwise behave as if offline (no matter what their actual connection status is). The room needs a PlayerTTL != 0. If a player is inactive for longer than PlayerTTL, the server will remove this player from the room. For a client "rejoining" a room, is the same as joining it: It gets properties, cached events and then the live events.

bool IsMasterClient
get

True if this player is the Master Client of the current room.

See also: PhotonNetwork.MasterClient.

string NickName
getset

Non-unique nickname of this player. Synced automatically in a room.

A player might change his own playername in a room (it's only a property). Setting this value updates the server and other players (using an operation).

string UserId
getset

UserId of the player, available when the room got created with RoomOptions.PublishUserId = true.

Useful for PhotonNetwork.FindFriends and blocking slots in a room for expected players (e.g. in PhotonNetwork.CreateRoom).

Online Documentation  -  Dashboard  -  Support Forum Exit Games GmbH