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