Skip to main content

Players

Contains functions for interacting with players.

info

This module can only be used in Entity scripts.

Properties

All

Indicates a method call applies to all connected clients. This property is read-only.

Functions

getPlayer(target)

Returns the player specified by client ID.

Parameters

  • target 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). Players can rotate only on Y axis which changes the direction they are facing.

Parameters

  • target Either the target Player, client ID of the target player.
  • rotation The rotation (in degrees) to set for the player(s).

Example

Set player rotation to 90 when it enters a sensor, also disable player controls.

function onPlayerEnter(player)
Players.setRotation(player, 90)
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

setAvatarOverrides(player, items)

Overrides items equipped on the avatar of the specified player.

Parameters

  • player Either the target Player, client ID of the target player.
  • items IDs of the avatar items to use to override. All the possible IDs should appear on your editor as an autocomplete option once you open quotes ("").

Example

Equip a baseball hat and top on every player that joins the world.

function onPlayerJoin(player)
Players.setAvatar(player, { "hat.baseball.0", "top.akiva.0" })
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

  • target Either the target Player, client ID of the target player.
  • color Color to set.

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

setRespawnPosition(target, position)

Sets the position a player should respawn after they fall into water or a destroyed.

Parameters

  • target Either the target Player, client ID of the target player.
  • position Vector3 to set.

Example

Change the respawn position of a player to (0,2,0).

function onPlayerJoin(player)
Players.setRespawnPosition(player, Vector3.new(0,2,0)
end

setXRayActive(target, active)

Sets x-ray vision effect for specific players.

Parameters

  • target Either the target Player, client ID of the target player.
  • active If the target should have x-ray vision.

Example

Disable x-ray vision on a player that joins the world.

function onPlayerJoin(player)
Players.setXRayActive(player, false)
end