Skip to main content

Hud

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

Leaderboard Functions​

leaderboard.setScore(target, score)​

Sets the score for the player specified by client ID.

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
Result

leaderboard.removeScore(target)​

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

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
Result

leaderboard.reset()​

Removes all scores from the leaderboard.

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
Result

leaderboard.setAscending()​

Switches leaerboard sorting to ascending.

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.

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.

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
Result

leaderboard.hide(target)​

Hides the leaderboard for a specific player.

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
Result

Timer Functions​

timer.show(target)​

Shows the timer for a specific player.

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
Result

timer.hide(target)​

Hides the timer for a specific player.

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
Result

timer.startCountdown(duration, callback)​

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

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
Result

timer.startCountup()​

Starts the timer counting up.

Example​

Start the countup at the start.

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

timer.stop()​

Stops the timer completely.

Example​

Stops the timer after 2 seconds.

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

timer.pause()​

Pauses timer. Use resume() to resume.

Example​

Pause the timer after 3 seconds.

function onStart()
    local player = Players.getRandomPlayer()
    Hud.timer.startCountup()
    Hud.timer.show(player)
    Task.wait(3)
    Hud.timer.pause()
end
Result

timer.resume()​

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

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
Result

timer.setCompleteCallback(callback)​

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

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
Result

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.

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
Result

timer.removeCallback(callback)​

Removes the callback function.

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
Result

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
Result

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
Result

Canvas Functions​

canvas.delete(id)​

Deletes the item specified by ID.

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.

Example​

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

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