User
A User is a type of entity which provides information about a real person connected to the game. You can get all the User entities from the World (GetUsers or ForEachUser). You can also get a User from a Character (which gives the User who is controlling that Character). User derives from Entity so if you have a User you can do any of these functions as well as the functions in Entity. You can do entity:IsA(User) to see if a particular entity variable is a User type entity.
Functions
| Function Name | Usage | Description | Notes |
|---|---|---|---|
| GetUsername | Text user:GetUsername() |
Get the display name of the User. | |
| GetPlayerCardIcon | string user:GetPlayerCardIcon() |
||
| SpawnPlayer | Character user:SpawnPlayer(Template playerTemplate) |
Spawn a player Entity for this User using the supplied template asset. | Server Only |
| SpawnPlayer | Character user:SpawnPlayer(Template playerTemplate, Locator locatorEntity) |
Spawn a player Entity for this User using the supplied template asset, | |
| at the position and rotation of the locatorEntity. | Server Only | ||
| SpawnPlayer | Character user:SpawnPlayer(Template playerTemplate, Vector position, Rotation rotation) |
Spawn a player Entity for this User using the supplied template asset, | |
| at the given position and rotation. | Server Only | ||
| SpawnPlayerWithEffect | Character user:SpawnPlayerWithEffect(Template playerTemplate, callback onEffectEnded) |
Spawn a player Entity for this User using the supplied template asset and trigger the spawn effect with callback | Server Only |
| SpawnPlayerWithEffect | Character user:SpawnPlayerWithEffect(Template playerTemplate, Locator locatorEntity, callback onEffectEnded) |
Spawn a player Entity for this User using the supplied template asset, | |
| at the position of the spawnPoint (which can be any Entity with a 'playerstart' component) and trigger the spawn effect with callback | Server Only | ||
| SpawnPlayerWithEffect | Character user:SpawnPlayerWithEffect(Template playerTemplate, Vector position, Rotation rotation, callback onEffectEnded) |
Spawn a player Entity for this User using the supplied template asset, | |
| at the given position and trigger the spawn effect | Server Only | ||
| SpawnPlayerWithEffect | Character user:SpawnPlayerWithEffect(Template playerTemplate) |
Spawn a player Entity for this User using the supplied template asset and trigger the spawn effect with callback | Server Only |
| SpawnPlayerWithEffect | Character user:SpawnPlayerWithEffect(Template playerTemplate, Locator locatorEntity) |
Spawn a player Entity for this User using the supplied template asset, | |
| at the position of the spawnPoint (which can be any Entity with a 'playerstart' component) and trigger the spawn effect. | Server Only | ||
| SpawnPlayerWithEffect | Character user:SpawnPlayerWithEffect(Template playerTemplate, Vector position, Rotation rotation) |
Spawn a player Entity for this User using the supplied template asset, | |
| at the given position and trigger the spawn effect | Server Only | ||
| DespawnPlayer | user:DespawnPlayer() |
Despawn a player | Server Only |
| DespawnPlayerWithEffect | user:DespawnPlayerWithEffect(callback onEffectEnded) |
Despawn a player and trigger the despawn effect with callback when it finishes | Server Only |
| DespawnPlayerWithEffect | user:DespawnPlayerWithEffect() |
Despawn a player and trigger the despawn effect | Server Only |
| GetPlayer | Entity user:GetPlayer() |
Get the Entity (if there is one) that has been spawned for the User. | |
| For now this is always a Character entity. | |||
| SetCamera | user:SetCamera(Entity cameraEntity) |
Set camera view of this User to the given cameraEntity (which can | |
| be either a Camera entity or a Character entity). | Server Only | ||
| SetCamera | user:SetCamera(Entity cameraEntity, number transitionTime) |
Set camera view of this User to the given cameraEntity (which can | |
| be either a Camera entity or a Character entity). Transitions the camera over a given time from the previous one. | Server Only | ||
| GetCamera | Camera user:GetCamera() |
||
| GetCameraLookAtPos | Vector user:GetCameraLookAtPos() |
Get the point the camera is looking at | |
| GetCameraLookAt | Vector,Vector user:GetCameraLookAt() |
Return two values, the position of the camera and a point the camera is facing at (where it collides with the scene). | |
| LeaveGame | user:LeaveGame() |
Server Only, Local Only | |
| LeaveGame | user:LeaveGame(callback travelFailedCallback) |
Server Only | |
| GoToGame | user:GoToGame(string gameId) |
Server Only, Local Only | |
| GoToGame | user:GoToGame(string gameId, callback travelFailedCallback) |
Server Only | |
| GoToWorld | user:GoToWorld(WorldAsset worldAsset) |
Send this user to another world on a separate server. If a world isn't provided, they'll be sent to the Game Settings Default World. | Server Only, Local Only |
| GoToWorld | user:GoToWorld(WorldAsset worldAsset, callback travelFailedCallback) |
Send this user to another world on a separate server. If a world isn't provided, they'll be sent to the Game Settings Default World. | Server Only |
| OpenStore | user:OpenStore() |
Server Only, Local Only | |
| OpenNews | user:OpenNews() |
Server Only, Local Only | |
| OpenGameHelp | user:OpenGameHelp(string helpPageId) |
Server Only, Local Only | |
| OpenGameHelp | user:OpenGameHelp() |
Server Only, Local Only | |
| OpenGameControls | user:OpenGameControls(string controlSchemeId) |
Server Only, Local Only | |
| OpenGameControls | user:OpenGameControls() |
Server Only, Local Only | |
| ShowCursor | user:ShowCursor(bool showCursor) |
Turn the cursor on or off | Deprecated |
| ProjectPositionToScreen | Vector2D user:ProjectPositionToScreen(Vector worldLocation) |
Converts a position in world space to a screen space co-ordinate | |
| Returned on-screen values are in the range 0 to 1 |
Usage example:
function MyPlayerScript:LocalOnTick(deltaTime)
local user = self:GetEntity():GetUser()
local screenPos = user:ProjectPositionToScreen(Vector.New(0,0,0))
Printf("Screen pos: {1}", screenPos)
end | Local Only |
| ProjectPositionToWidget { #Function_ProjectPositionToWidget} | Vector2D user:ProjectPositionToWidget(Widget widget, Vector worldLocation) | Converts a position in world space to a widget space co-ordinate
Returned on-screen values are in the range 0 to 1
Usage example:
function MyPlayerScript:LocalOnTick(deltaTime)
local user = self:GetEntity():GetUser()
local widget = self:GetEntity().widget
local screenPos = user:ProjectPositionToWidget(widget, Vector.New(0,0,0))
Printf("Screen pos: {1}", screenPos)
end | Local Only |
| PlayVibrationEffect { #Function_PlayVibrationEffect} | user:PlayVibrationEffect(VibrationEffectAsset vibrationEffect) | | |
| PlayManualVibration { #Function_PlayManualVibration} | user:PlayManualVibration(number intensity, number duration, bool affectSmallMotors, bool affectLargeMotors) | | |
| PlayCameraShakeEffect { #Function_PlayCameraShakeEffect} | user:PlayCameraShakeEffect(CameraShakeAsset cameraShake, number scale) | Play a camera shake effect on this User with a scale multiplier | |
| PlayCameraShakeEffect | user:PlayCameraShakeEffect(CameraShakeAsset cameraShake) | Play a camera shake effect on this User | |
| SetMoveOverride { #Function_SetMoveOverride} | user:SetMoveOverride(Vector2D scale, Vector2D add) | Set a scale on the user's actual move input and an addition 2D vector to add to it. Used for
example to auto-walk a player forward but scaling the real input down to zero and adding an
additional value. | |
| SetLookOverride { #Function_SetLookOverride} | user:SetLookOverride(Vector2D scale, Vector2D add) | Set a scale on the user's actual look input and an addition 2D vector to add to it. Used for
example to auto-look a player at a particular point by scaling the real input down to zero
and adding an additional value. | |
| SetLeaderboardValue { #Function_SetLeaderboardValue} | user:SetLeaderboardValue(string leaderboardId, number value, callback callback) | | |
| SetLeaderboardValue | user:SetLeaderboardValue(string leaderboardId, number value) | | |
| GetLeaderboardValue { #Function_GetLeaderboardValue} | user:GetLeaderboardValue(string leaderboardId, callback callback) | Gets the highest ranking value on the specified leaderboard for this user.
Results are returned as parameters to the callback function.
Callback function parameters are Score & Rank | |
| AddToLeaderboardValue { #Function_AddToLeaderboardValue} | user:AddToLeaderboardValue(string leaderboardId, number increment, callback callback) | Add a number to the leaderboard value on the specified leaderboard for this user.
Results are returned as parameters to the callback function.
Callback function parameter is the new score | Server Only |
| AddToLeaderboardValue | user:AddToLeaderboardValue(string leaderboardId, number increment) | Add a number to the leaderboard value on the specified leaderboard for this user. | Server Only |
| GetChallengeProgress { #Function_GetChallengeProgress} | number user:GetChallengeProgress(string challengeId) | Gets the current progress on an active challenge | |
| SendChallengeEvent { #Function_SendChallengeEvent} | user:SendChallengeEvent(string eventName, table eventParametersTable) | Please use SendGameEvent instead of this. SendGameEvent trigger Challenges and Activities | Deprecated, Server Only |
| SendChallengeEvent | user:SendChallengeEvent(string eventName) | Please use SendGameEvent instead of this. SendGameEvent trigger Challenges and Activities | Deprecated, Server Only |
| SendXPEvent { #Function_SendXPEvent} | user:SendXPEvent(string eventName, table eventParametersTable) | Sends an event for this user that can be used by the Challenges and Activities systems.
Takes a lua table of named parameters which are checked against the conditions inside each challenge and activity. Example | Server Only |
| SendXPEvent | user:SendXPEvent(string eventName) | Sends an event for this user that can be used by the Challenges and Activities systems. This is the same as sending an
empty parameter list in the other SendXPEvent overload. | Server Only |
| GetBattlePassInfo { #Function_GetBattlePassInfo} | table user:GetBattlePassInfo() | Get whether this player has the current battle pass and what level they are on | |
Parameters
| Parameter Name | Usage | Description | Notes |
|---|---|---|---|
| showDefaultCrosshair | bool showDefaultCrosshair |
Show the default crosshair | |
| useHotbar | bool useHotbar |
Use hotbar inputs, using the next and previous item buttons on controller and the hotbar buttons on keyboard | |
| hotbarMax | int hotbarMax |
Number of slots in the hotbar, this is a wrap point for next and previous item buttons | |
| hotbarIndex | int hotbarIndex |
The current (1-based) hotbar index for this user | |
| voiceChannel | int voiceChannel |
The current voice channel for this user (1 - 32) |
Overrides
| Override Name | Usage | Description | Notes |
|---|---|---|---|
| new_index | user.var = object value |
Examples
user:SendXPEvent(string eventName, table eventParametersTable)
Here's an example of sending an event called SomeEvent which will progress any matching challenges or trigger any activities
and give the player XP.
The parameter names are entirely up to you and will be compared against the conditions in the definitions.
self:GetEntity():GetUser():SendXPEvent("SomeEvent", {someParameter1 = someValue1, someParameter2 = someValue2})