GFX Leaderboard

A kill/death leaderboard system for FiveM with an in-game NUI scoreboard, 3D podium pedestals displaying the top players as peds with their skins, real-time stat tracking, per-weapon statistics, and profile cards.

Info

Dependencies

Installation

1. Import the SQL table

The script auto-creates the gfx_leaderboard table on first start. Alternatively, you can import it manually:

CREATE TABLE IF NOT EXISTS `gfx_leaderboard` (
  `id` VARCHAR(255) NOT NULL PRIMARY KEY,
  `name` longtext DEFAULT NULL,
  `kills` int(11) DEFAULT NULL,
  `deaths` int(11) DEFAULT NULL,
  `gunskill` longtext DEFAULT NULL,
  `gunsdeath` longtext DEFAULT NULL,
  `image` longtext DEFAULT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;

2. Copy Files

Place gfx-leaderboard into your resources folder.

3. server.cfg

ensure gfx-lib
ensure gfx-leaderboard

Make sure gfx-lib starts before gfx-leaderboard.

Configuration

All configuration is in config.lua.

Peds Configuration

Each entry in Config.Peds defines a leaderboard category podium. By default, there are two: kills and deaths.

Peds = {
    ["kills"] = {
        enable = true,                          -- Enable/disable this podium
        platformColor = "blue",                 -- Platform prop color suffix
        platformCoords = {
            coords = vector3(335.68, -214.36, 53.15),  -- Platform position
            heading = 112.0                              -- Platform heading
        },
        pedCoords = {                           -- Positions for top 3 peds
            [1] = vector4(...),                 -- 1st place
            [2] = vector4(...),                 -- 2nd place
            [3] = vector4(...),                 -- 3rd place
        }
    },
    ["deaths"] = { ... }
}

Weapon Labels & Hashes

• WeaponLabels maps internal weapon names (e.g., "weapon_pistol") to display names (e.g., "Pistol"). Used in the profile card to show most-used weapons.
• WeaponHash maps GTA weapon hash keys to weapon name strings. Only weapons listed here are tracked per-weapon. Add new entries to track additional weapons.

Exports

Client Exports

FloatyDraw

Renders floating 3D text/content on a render target prop at world coordinates. Used internally for podium ped info, but available for other resources.

exports['gfx-leaderboard']:FloatyDraw(coords, heading, callback)

Parameters:

Returns: nil on success, or a string error message ("Not on screen", "Point out of range", "Not a visible angle", "Too many targets!", "Failed callback: ...")

Notes:

• Maximum 19 simultaneous render targets per frame
• Automatically handles visibility culling (off-screen, distance > 100, wrong angle)
• The render target prop background is transparent

Events

No public API events are exposed for external use.

The script internally listens to gfx-lib:server:onDeath (provided by gfx-lib) to automatically track kills and deaths. No manual event triggering is required.

Commands

Features

• Real-time kill/death tracking -- Automatically tracks kills and deaths via gfx-lib:server:onDeath event, including weapon identification
• NUI scoreboard -- Full-featured browser-based UI with pagination, sorting by kills or deaths, and player profile cards
• 3D podium display -- Physical in-world platforms with the top 3 players rendered as peds wearing their actual character skins
• Floating stat text -- Render-target-based floating text above podium peds showing name, kills, deaths, and K/D ratio
• Per-weapon statistics -- Tracks which weapons each player uses most for kills and deaths, displayed on profile cards
• Player profile photos -- Fetches player avatars from Steam or Discord for display in the leaderboard
• Auto-save -- Periodically saves leaderboard data to the database (configurable interval, default 30 minutes)
• Save on disconnect -- Player stats are saved to the database when they leave the server
• Save on resource stop -- All data is persisted when the resource stops
• Auto table creation -- The database table is created automatically if it does not exist
• Live rank updates -- When a player overtakes another in rankings, podium peds are swapped in real-time for all clients
• Multi-framework support -- Works with ESX, QBCore, and standalone servers through gfx-lib
• Multiple skin script support -- Compatible with qb-clothes, esx_skin, skinchanger, fivem-appearance, and illenium-appearance

Troubleshooting

Source

• GitHub: https://github.com/gfx-fivem/gfx-leaderboard
• Organization: GFX-Fivem