Skip to content

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