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

hasPersistentData(target, key)​

Returns true if the cache has data for the specified player.

Parameters​

  • target — The target Player or client ID of the target player.
  • key — String identifier for the data value.

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.setAvatarOverrides(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

setStaminaDrain(target, time)​

Sets the duration that a player can dash with a full stamina meter.

Parameters​

  • target — Either the target Player, client ID of the target player.
  • time — Maximum dash duration in seconds. Set to 0 or lower for infinite dash.
    • Min: -1
    • Max: 3600

setStaminaRegen(target, time)​

Sets the time it takes to refill an empty stamina meter.

Parameters​

  • target — Either the target Player, client ID of the target player.
  • time — Time to fill stamina in seconds. Set to 0 or lower to disable refill.
    • Min: -1
    • Max: 3600

setGuardStaminaRegen(target, time)​

Sets the time it takes to refill an empty stamina meter if depleted by guarding.

Parameters​

  • target — Either the target Player, client ID of the target player.
  • time — Time to fill stamina in seconds. Set to 0 or lower to disable refill.
    • Min: -1
    • Max: 3600

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

getSpeed(target)​

Returns the movement speed of the target player.

Parameters​

  • target — The target Player or client ID of the target player.

getDashSpeed(target)​

Returns the dash speed of the target player.

Parameters​

  • target — The target Player or client ID of the target player.

getJumpPower(target)​

Returns the jump power of the target player.

Parameters​

  • target — The target Player or client ID of the target player.

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