Player Reference Token
Generally, remote calls and chat can only be sent to a player from the area/instance they are currently in and the world server. Additionally, Hero Engine has used the mechanics described on this page in its system area implementation, allowing system areas to also communicate directly with a player. For an understanding of how that implementation works, read on.
In order to offload processing from the world server, the player reference system is available to allow servers to communicate with a player. This requires your code to follow three steps:
- Acquire a string token for the player from the world server or area/instance that the player is in;
- Transmit that token to the area/instance that wants to reference the player;
- Create a local reference to the player using that token.
Once those three steps are done, the area/instance where the local reference was created will be able to send remote calls to the player's client, and send chat to that player as if he/she was logged into that area. Note that sending chat in this case specifically means using the
MsgPlayer() external function or the
When an area no longer needs to reference a player, because they have logged out of the game for example, each area is responsible for cleaning up a reference that it created to that player. Note that tokens created in step #1 are session-dependent, so in the case of an account logging off and back on, an new token must be acquired and then used to create a new reference for that account.
Automatic Player Reference
When a player's account node is replicated to another server, the system automatically registers the player in the other server. This allows communication with the player the same as if this token system were used. When the account is no longer replicated, communication to the player again relies on the existence of a local reference. In other words, the two systems independently provide the communication pathway. They do no depend on or effect each other.
The following external functions provide the mechanics necessary to acquire a token for a player, use a token to create a local reference, and to destroy a local reference. Additionally, another external function will be added to query the IDs of all existing local references.
The following function creates a string token for a player from its playerAccount ID. This function can only be used on the world server, or in the area/instance that the player is loaded into. Attempts to use the function in other area/instances will cause a script error to be thrown.
external function GetPlayerReferenceToken(playerAccountID as ID) as String
The following function takes a token created generated by
GetPlayerReferenceToken() and creates a local reference to the player it was generated from. If a local reference already exists or the token string is invalid, it will return
false. Otherwise it will return
external function CreatePlayerReferenceFromToken(playerToken as String) as Boolean
The following function deletes an existing local reference to a player. If no local reference exists for the specified ID, it will return
false. Otherwise it will return
external function RemovePlayerReference(playerAccountID as ID) as Boolean
The following function returns a list of all existing local references to players. This list includes any players loaded in the area.
external function ListPlayerReferences() as List of ID