Players
Contains functions for interacting with players.
Properties
All
Indicates a method call applies to all connected clients. This property is read-only.
Functions
getPlayer(clientId)
Returns the player specified by client ID.
Parameters
- clientId — The client ID of the target player.
Returns
The Player, or nil if none was found.
Example
Get the Player when an Entity starts interacting and use that name in the speech prompt.
function onInteractStart(clientId)
local playerInteracting = Players.getPlayer(clientId)
Speech.prompt("Hello " .. playerInteracting.name)
end
getRandomPlayer()
Returns a random player.
Returns
The Player, or nil if none was found.
Example
Make a random player a Boss every 5 seconds.
local currentBoss = nil
local function changeBoss()
local randomPlayer = Players.getRandomPlayer()
currentBoss = randomPlayer
Task.wait(5)
changeBoss()
end
function onStart()
changeBoss()
end
getAllPlayers()
Returns all players currently connected.
Returns
All connected players, or empty array if none were found.
Example
Say hi to all the players in the world when we interact with an NPC.
function onInteractStart(clientId)
local allPlayers = Players.getAllPlayers()
local text = "Nice to have you here "
for p in allPlayers do
text = text .. p.name .. ", "
end
text = text .. "I hope you have a good experience"
Speech.prompt(text)
end
teleport(target, targetPosition)
Teleports the player(s) to the specified position.
Parameters
- target — Either the target Player, client ID of the target player.
- targetPosition — A Vector3 of the position to teleport the player(s).
Example
Teleport a player to (0,0,0) when it enters a sensor.
function onPlayerEnter(player)
Players.teleport(player, Vector3.new(0,0,0))
end
setRotation(target, rotation)
Sets the rotation of the player(s).
Parameters
- target — Either the target Player, client ID of the target player.
- rotation — A Vector3 of the rotation to set for the player(s).
Example
Set player rotation to (90,0,0) when it enters a sensor, also disable player controls.
function onPlayerEnter(player)
Players.setRotation(player, Vector3.new(90,0,0))
Controls.setPlayerControls(player, false)
end
setInvulnerability(target, invulnerable)
Sets the invulnerability of the player(s).
Parameters
- target — Either the target Player, client ID of the target player.
- invulnerable — A boolean that sets invulnerability on the player(s).
Example
Set a player invulnerable when it joins the world.
function onPlayerJoin(player)
Players.setInvulnerability(player, true)
end
getData(target, key)
Returns cached data stored for the specified player.
Parameters
- target — Either the target Player, client ID of the target player.
- key — A string containing the key used to identify the data cache.
Example
Get the cached score for a specific player when it enters a sensor and display it in the leaderboard.
function onPlayerEnter(player)
local score = Players.getData(player, "score")
Hud.leaderboard.setScore(player, score)
end
setData(target, key, value)
Stores data in a cache for the specified player.
Parameters
- target — Either the target Player, client ID of the target player.
- key — A string containing the key used to identify the data cache.
- value — The data to store in the cache.
Example
Store the score of the player when he dies.
function onPlayerDestroy(player)
local score = Players.getData(player, "score")
score = score - 10
Players.setData(player, "score", score)
end
getPersistentData(target, key)
Returns persistent data stored for the specified player.
Parameters
- target — Either the target Player, client ID of the target player.
- key — A string containing the key used to identify the data cache.
Returns
The value stored, or nil if nothing was stored.
Example
Get the persistent score that the player had in previous sessions in this world, and store it in the player cache.
function onPlayerJoin(player)
local score = Players.getPersistentData(player, "score")
Players.setData(player, "score", score)
end
setPersistentData(target, key, value)
Stores data in a cache for the specified player.
Parameters
- target — Either the target Player, client ID of the target player.
- key — A string containing the key used to identify the data cache.
- value — The data to store in the cache. Must be either a boolean, number or string.
Example
Set the persistent score of the player when he leaves the world, so we can use it when he joins the world in the future.
function onPlayerLeave(player)
local score = Players.getData(player, "score")
Players.setPersistentData(player, "score", score)
end
setSpeed(target, speed)
Sets the maximum speed of the player. Must between 1 and 10. Default is 3.
Parameters
- target — Either the target Player, client ID of the target player.
- speed — Maximum running speed.
- Min: 1
- Max: 10
Example
Set the speed of the player to 10 when it interacts with an NPC.
function onInteractStart(clientId)
Players.setSpeed(clientId, 10)
end
setDashSpeed(target, speed)
Sets the maximum speed of the player dash. Must be between 1 and 10. Default is 8.
Parameters
- target — Either the target Player, client ID of the target player.
- speed — Maximum dash speed.
- Min: 1
- Max: 10
Example
Set the dash speed of the player to 3 when it joins the world.
function onPlayerJoin(player)
Players.setDashSpeed(player, 3)
end
setJumpPower(target, power)
Sets the amount of power used for the player to jump. Must be between 1 and 10. Default is 5.
Parameters
- target — Either the target Player, client ID of the target player.
- power — Jump power.
- Min: 1
- Max: 10
Example
Set the jump power of the player to 8 when it interacts with an NPC.
function onInteractStart(clientId)
Players.setJumpPower(clientId, 8)
end
setRingColor(target, color)
Sets the color of the indicator ring below the player.
Parameters
Example
Change the ring color of a player to a random one everytime he enters a sensor.
function onPlayerEnter(player)
local r = math.random(0,255)
local g = math.random(0,255)
local b = math.random(0,255)
local color = Color.new(r,g,b)
Players.setRingColor(player, color)
end