Skip to main content

scoreboard — Scoreboard API

Phase: Server

Manage scoreboard objectives and player scores.

scoreboard.get(playerName, objective) → int | nil​

Returns the score for playerName in objective, or nil if the objective doesn't exist.

local kills = scoreboard.get("Notch", "kills")
if kills then
  server.broadcast("Notch has " .. kills .. " kills!")
end

scoreboard.set(playerName, objective, value)​

Sets the score for playerName in objective to the given integer value.

scoreboard.set("Notch", "kills", 0)   -- reset kills

scoreboard.add(playerName, objective, delta) → int​

Adds delta to the current score and returns the new value.

local newScore = scoreboard.add("Notch", "kills", 1)
server.broadcast("Notch now has " .. newScore .. " kills!")

scoreboard.reset(playerName, objective)​

Resets (removes) the score entry for playerName in objective.

scoreboard.createObjective(name, displayName)​

Creates a new dummy-type scoreboard objective. Does nothing if an objective with that name already exists.

scoreboard.createObjective("kills", "Player Kills")
scoreboard.createObjective("deaths", "Deaths")

scoreboard.getObjectives() → table​

Returns a sequential table of all current objective names.

for _, name in ipairs(scoreboard.getObjectives()) do
  print(name)
end

Full Example​

-- startup: ensure objective exists
scoreboard.createObjective("kills", "Kills")

-- server_scripts: count kills on death
onEvent("player.death", function(e)
  scoreboard.add(e.player.name, "kills", 1)
  e.player.tell("You have died " .. scoreboard.get(e.player.name, "kills") .. " time(s).")
end)