esx_scoreboard

esx_scoreboard is a player list for ESX Legacy that players open with a key (default Z). It shows every online player with server id, character name, job, grade and ping, a counter per job, a search bar, and a list of ongoing activities such as robberies or races that other resources push in through server exports.

OverviewCopy Anchor Link

The server keeps an in-memory cache of players and job counts. It updates it on esx:playerLoaded, esx:setJob, esx:jobDataRefreshed and playerDropped, and runs a full reconcile every minute as a safety net. Data is only sent to players who currently have the scoreboard open, and the list is paged, so it scales to large servers.

InstallationCopy Anchor Link

ensure esx_lib
ensure es_extended
ensure esx_scoreboard

The UI ships prebuilt in web/dist. To change the Svelte source, run npm install and npm run build in web (Node.js 18 or newer).

UsageCopy Anchor Link

• Press Z or run /scoreboard to toggle it. Press ESC to close it.
• Search filters by player name, job label or server id.
• While it is open, camera look and attack controls are disabled.

ConfigurationCopy Anchor Link

All keys are in config/main.lua.

DisplayCopy Anchor Link

Config.Jobs = {
  police = { label = "Police", color = "#3B82F6" },
  ambulance = { label = "EMS", color = "#EF4444" },
  -- mechanic, taxi, realtor, cardealer, banker ...
}

Config.ActivityTypes = {
  robbery = { label = "Robbery", icon = "💰" },
  -- heist, drug, race, hostage, shootout
}

Jobs that are not listed in Config.Jobs are still counted; they just use the default color.

Performance and limitsCopy Anchor Link

Server exportsCopy Anchor Link

Use these from your own server scripts (robberies, heists, races) to show what is going on in the city.

AddActivityCopy Anchor Link

local id = exports.esx_scoreboard:AddActivity(activityType, label, location, players)

Returns the numeric activity id, or -1 if the type is invalid.

UpdateActivityCopy Anchor Link

local ok = exports.esx_scoreboard:UpdateActivity(id, { label = '...', location = '...', players = { ... } })

Only the fields you pass are changed. Returns true when the activity was found.

RemoveActivityCopy Anchor Link

local ok = exports.esx_scoreboard:RemoveActivity(id)

Returns true when the activity was found and removed.

GetActiveActivitiesCopy Anchor Link

local list = exports.esx_scoreboard:GetActiveActivities()

Returns a copy of all activities. Each entry has id, type, label, location, startTime (os.time()) and players.

Example: store robberyCopy Anchor Link

local activeRobberies = {}

RegisterNetEvent('myrobbery:start', function(storeName)
    local src = source
    -- validate distance, cooldown and police count here
    activeRobberies[src] = exports.esx_scoreboard:AddActivity('robbery', storeName, 'Grove Street', { src })
end)

local function endRobbery(src)
    local id = activeRobberies[src]
    if id then
        exports.esx_scoreboard:RemoveActivity(id)
        activeRobberies[src] = nil
    end
end

AddEventHandler('playerDropped', function()
    endRobbery(source)
end)

Activities are not removed automatically. Always remove them when the event ends, including when the player disconnects.

Network eventsCopy Anchor Link

The client-triggerable events only return public data (names, jobs, ping) and are rate limited, so they cannot be abused for more than reading the player list.

Common issuesCopy Anchor Link

• "ESX.GetJobs() unavailable after 10 attempts": es_extended was not ready. Make sure it starts before esx_scoreboard.
• Changing OpenKey has no effect: FiveM saves key mappings per player. Existing players must rebind it themselves.
• Players missing right after restart: the cache is rebuilt from GetPlayers() once ESX jobs are available; wait for the first reconcile or reopen the list.
• Old robberies stay on the board: your script never called RemoveActivity.

RelatedCopy Anchor Link

• esx_pausemenu
• esx_policejob
• esx_lib
• Server functions

Frequently asked questions