Skip to main content

Hud

Contains functions to customize and control the Heads-Up Display (HUD).

Functions

getItemByName(name)

Returns the Hud item with the specified name.

info

This method can only be used in Hud scripts.

Parameters

  • name Name of the item.

getItem(id)

Returns the Hud item with the specified ID.

info

This method can only be used in Hud scripts.

Parameters

  • id Name of the item.

delete(id)

Deletes the Hud item specified by ID.

info

This method can only be used in Hud scripts.

Parameters

  • id ID of the target item.

Example

Delete a button.

-- ... button created and elsewhere
Hud.delete(buttonId)

clear()

Deletes all items in the Hud canvas.

info

This method can only be used in Hud scripts.

Example

Clear the canvas with all the Hud items.

-- ... Hud items created elsewhere
Hud.clear()

Leaderboard Functions

leaderboard.setScore(target, score)

Sets the score for the player specified by client ID.

info

This method can only be used in Entity scripts.

Parameters

  • target Either the target Player, client ID of the target player.
  • score Value of the score.

Example

Set an initial score of 100.

function onStart()
local player = Players.getRandomPlayer()
Hud.leaderboard.show(player)
Hud.leaderboard.setScore(player, 100)
end

leaderboard.removeScore(target)

Removes the score in the leaderboard for the player specified by client ID.

info

This method can only be used in Entity scripts.

Parameters

  • target Either the target Player, client ID of the target player.

Example

Remove a player from the leaderboard after 2 seconds.

function onStart()
local player = Players.getRandomPlayer()
Hud.leaderboard.setScore(player, 100)
Hud.leaderboard.show(player)
Task.wait(2)
Hud.leaderboard.removeScore(player)
end

leaderboard.reset()

Removes all scores from the leaderboard.

info

This method can only be used in Entity scripts.

Example

Reset the leaderboard after 2 seconds.

function onStart()
local player = Players.getRandomPlayer()
Hud.leaderboard.setScore(player, 100)
Hud.leaderboard.show(player)
Task.wait(2)
Hud.leaderboard.reset()
end

leaderboard.setAscending()

Switches leaerboard sorting to ascending.

info

This method can only be used in Entity scripts.

Example

Set the leaderboard to an ascending sort at the start (lower scores will show first).

function onStart()
Hud.leaderboard.setAscending()
end

leaderboard.setDescending()

Switches leaerboard sorting to descending.

info

This method can only be used in Entity scripts.

Example

Set the leaderboard to a descending sort at the start (higher scores will show first).

function onStart()
Hud.leaderboard.setDescending()
end

leaderboard.show(target)

Shows the leaderboard for a specific player.

info

This method can only be used in Entity scripts.

Parameters

  • target Either the target Player, client ID of the target player.

Example

Show the leaderboard.

function onStart()
local player = Players.getRandomPlayer()
Hud.leaderboard.setScore(player, 100)
Hud.leaderboard.show(player)
end

leaderboard.hide(target)

Hides the leaderboard for a specific player.

info

This method can only be used in Entity scripts.

Parameters

  • target Either the target Player, client ID of the target player.

Example

Hide the leaderboard after 2 seconds.

function onStart()
local player = Players.getRandomPlayer()
Hud.leaderboard.setScore(player, 100)
Hud.leaderboard.show(player)
Task.wait(2)
Hud.leaderboard.hide(player)
end

Timer Functions

timer.show(target)

Shows the timer for a specific player.

info

This method can only be used in Entity scripts.

Parameters

  • target Either the target Player, client ID of the target player.

Example

Show the timer.

function onStart()
local player = Players.getRandomPlayer()
Hud.timer.show(player)
end

timer.hide(target)

Hides the timer for a specific player.

info

This method can only be used in Entity scripts.

Parameters

  • target Either the target Player, client ID of the target player.

Example

Hide the timer after 2 seconds.

function onStart()
local player = Players.getRandomPlayer()
Hud.timer.show(player)
Task.wait(2)
Hud.timer.hide(player)
end

timer.startCountdown(duration, callback)

Starts the timer countdown. If a callback function is specified, it will be called when the timer reaches zero.

info

This method can only be used in Entity scripts.

Parameters

  • duration Duration of the countdown (in seconds).
  • callback Function that should be called when the timer reaches zero.

Example

Set the countdown to 5 seconds and show the leaderboard when it reaches zero.

function onStart()
local player = Players.getRandomPlayer()
Hud.leaderboard.setScore(player, 100)
Hud.leaderboard.show(player)
Hud.timer.show(player)
Hud.timer.startCountdown(5, function() Hud.leaderboard.hide(player) end)
end

timer.startCountup()

Starts the timer counting up.

info

This method can only be used in Entity scripts.

Example

Start the countup at the start.

function onStart()
local player = Players.getRandomPlayer()
Hud.timer.show(player)
Hud.timer.startCountup()
end

timer.stop()

Stops the timer for the specified player.

info

This method can only be used in Entity scripts.

Parameters

  • id Timer to stop.
  • target Player clientId or reference (-1 to stop for all Players).

timer.pause()

Pauses the timer for the specified player. Calling start on this timer will make it continue from its last value.

info

This method can only be used in Entity scripts.

Parameters

  • id Timer to pause.
  • target Player clientId or reference (-1 to pause for all Players).

timer.resume()

Resumes paused timer. This will do nothing if the timer is not running or stopped.

info

This method can only be used in Entity scripts.

Example

Pause the timer after 1 second, wait 2 seconds, and resumes the timer.

function onStart()
local player = Players.getRandomPlayer()
Hud.timer.startCountup()
Hud.timer.show(player)
Task.wait(1)
Hud.timer.pause()
Task.wait(2)
Hud.timer.resume()
end

timer.setCompleteCallback(callback)

Sets a callback function that will be called when the timer reaches zero.

info

This method can only be used in Entity scripts.

Parameters

  • callback Function that should be called when the timer reaches zero.

Example

Make a robot chase the player when the timer reaches zero.

local function chasePlayer()
while true do
Movement.moveToPlayer(AsyncMode.Continue)
Task.yield()
end
end

function onStart()
local player = Players.getRandomPlayer()
Hud.timer.startCountdown(5, nil)
Hud.timer.show(player)
Hud.timer.setCompleteCallback(chasePlayer)
end

timer.setTickCallback(callback)

Sets a callback function that will be called everytime the timer 'ticks'. Ticks happen approximately once per second, whilst the timer is active.

info

This method can only be used in Entity scripts.

Parameters

  • callback Function that should be called whenever the timer 'ticks'.

Example

Write on console a tick counter every time that the timer ticks.

local tickCounter = 0

local function tick()
tickCounter = tickCounter + 1
Hud.console.write("tick " .. tickCounter)
end

function onStart()
local player = Players.getRandomPlayer()
Hud.timer.show(player)
Hud.timer.startCountup()
Hud.timer.setTickCallback(tick)
end

timer.removeCallback(callback)

Removes the callback function.

info

This method can only be used in Entity scripts.

Parameters

  • callback Function that should be removed.

Example

After ticking 200 times, remove the callback.

local tickCounter = 0

local function tick()
tickCounter = tickCounter + 1
Hud.console.write("tick " .. tickCounter)
if tickCounter == 200 then
Hud.timer.removeCallback(tick)
end
end

function onStart()
local player = Players.getRandomPlayer()
Hud.timer.startCountup()
Hud.timer.show(player)
Hud.timer.setTickCallback(tick)
end

Console Functions

console.write(text)

Adds the specified text to the console.

Parameters

  • text Text to write to the console.

Example

Print in the console a welcome message.

function onStart()
Hud.console.write("welcome to my world!")
end

console.clear()

Clears all text from the console.

Example

Clear the console after 5 seconds.

function onStart()
Hud.console.write("This message will be clear in 5 seconds!")
Task.wait(5)
Hud.console.clear()
end

Canvas Functions

canvas.setSortOrder(id, sortOrder)

Set the sort order of a rect. Rects with higher values will appear on top of others.

Parameters

  • id ID of the target rect.
  • sortOrder Sorting order value.

canvas.setParent(id, parent)

Set one rect's position to be relative to another rect If the parent rect moves, this rect will follow it.

Parameters

  • id ID of the target rect.
  • parent ID of the rect the target will link to.

canvas.delete(id)

Deletes the item specified by ID.

info

This method can only be used in Entity scripts.

Parameters

  • id ID of the target item.

Example

Delete a button created.

-- ... button created and used somewhere.
Hud.canvas.delete(buttonId)

canvas.clear()

Deletes all items in the canvas.

info

This method can only be used in Entity scripts.

Example

Clear the canvas with all the hud items that we created.

-- ...
Hud.canvas.clear()

Enums

HudItemType

  • Rect value = 0
  • Textbox value = 1
  • Button value = 2
  • Timer value = 3
  • ProgressBar value = 4
  • Slider value = 5

MouseButton

  • Left value = 0
  • Right value = 1
  • Middle value = 2