About Players
When you need to edit some player-related logic, you need to use Player-Related Event Functions, ParaPlayer API, and ParaPlayerService API.
ParaPlayerService manages player objects in all rooms. Calling the API therein will query and obtain the player information.
ParaPlayer contains some basic properties of a player such as User ID, Nickname, Photo, Location, etc.. It also contains some functions that control the player such as setting the speed and changing actions, etc.. For player management, tag-related APIs are useful for assigning some data to players.
For detailed API usage and examples, please refer to API Reference.
Local Player
Local players are the player objects on the local client, in other words, "themselves."
Occasionally, it is necessary to perform some actions after getting "themselves" or to determine whether the player who performed certain actions is the local player.
Some APIs are available only for local players, such as ParaPlayer.Immobilize.
Below are the APIs commonly used for local players.
| ParaPlayerService.GetLocalPlayer() | Get local players |
| ParaPlayer.isLocal | Determine whether a player is the local player |
Player Tag
With a player tag, it's easy to store some information on players, which will be automatically synchronized across all clients in a room.
Tag is a key-value pair, with both key and value being strings.
For example, we can add such tags to a player:
- group：red
- role：scientist
| ParaPlayer.SetPlayerTag(tagName, tagValue) | Add tags to a player |
| ParaPlayer.GetPlayerTag(tagName) | Obtain tags of a player. |
| ParaPlayer.ClearPlayerTags(tagName) | Clear a specified tag from a player. All tags will be cleared if the parameter is empty. |
| ParaPlayerService.GetPlayersWithTag(tagName, tagValue) | Obtain all players with a specific tag. You can specify only the tagName or both the tagName and tagValue. |
| ParaPlayerService.ClearAllPlayersTag(tagName) | Clear a specific tag from all players. All tags will be cleared from all players if the parameter is empty. |
Tips for using tags
Since the same script will be run on all clients that enter the same room, tag-related APIs do not require extra authorization, which means that the code will be executed for all players. Please pay attention to the permissions' management when operating such APIs!
Common ways for using tags:
- Everyone sets his/her own tag, and it is read-only for others (using ParaPlayer.isLocal to determine if they are really "themselves");
- A master or a specific client sets everyone's tag, and it is read-only for others.
Updated almost 2 years ago