gfx-kit

Claimable kit system with NUI interface. Players open a UI panel to view and claim configured kits (items, weapons, armor, etc.) with per-kit cooldown timers. Supports conditional access via custom functions (e.g., Discord role checks).

Info

Dependencies

Installation

1. Copy files

Place the gfx-kit folder into your server's resources directory.

2. Import SQL (optional)

The script auto-creates the gfx_kits table on first boot. If you prefer manual setup, import kits.sql:

CREATE TABLE IF NOT EXISTS `gfx_kits` (
    `identifier` VARCHAR(64) NOT NULL,
    `kits` LONGTEXT DEFAULT NULL,
    PRIMARY KEY (`identifier`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;

3. server.cfg

ensure gfx-lib
ensure gfx-kit

Make sure gfx-lib starts before gfx-kit.

Configuration

All configuration is in config.lua.

General Settings

Kit Definition — Config.Kits

Each kit is defined as a key-value entry in Config.Kits. The key is the kit's unique identifier string.

Config.Kits = {
    ["starter"] = {
        name = "Starter Kit",              -- Display name in UI
        description = "This is a starter kit", -- Description shown in UI
        duration = 1,                       -- Cooldown in hours before kit can be claimed again
        image = "assets/armor.png",         -- Image path (relative to nui folder)
        items = {                           -- Items given when claimed
            { name = "weapon_carbinerifle", count = 1 },
            { name = "rifle_ammo", count = 1 },
            { name = "armor", count = 1 },
        },
        playerCanInteract = function(source) -- Access control function
            return true                      -- Return true to allow, false to lock
        end,
    },
}

Kit Options

Example: Discord Role-Gated Kit

["discord"] = {
    name = "Discord Kit",
    description = "Requires Discord Prime role",
    duration = 6,
    image = "assets/armor.png",
    items = {
        { name = "weapon_carbinerifle", count = 1 },
    },
    playerCanInteract = function(source)
        return HasPlayerHasRoleOnDiscord(source, "Prime")
    end,
},

Helper Functions

The config file also provides these utility functions:

Exports

No exports are created by this script.

Events

No public API events are exposed by this script. All internal events use a private callback system (gfx-kit:triggerCallback, gfx-kit:getKits, gfx-kit:claimKit) and are not intended for external use.

Commands

Features

• NUI Kit Panel — Full HTML/JS interface to browse, view, and claim kits.
• Configurable Kits — Define unlimited kits with custom names, descriptions, images, items, and cooldowns.
• Cooldown System — Per-kit cooldown timer stored in the database. Duration is configured per kit in hours. Players cannot claim the same kit until the cooldown expires.
• Conditional Access — Each kit has a playerCanInteract function that controls who can see/claim it. Useful for role-gated, job-gated, or permission-gated kits.
• Discord Integration — Built-in helper functions for checking Discord roles, enabling Discord-exclusive kits.
• Auto Table Creation — The gfx_kits database table is automatically created if it does not exist on server start.
• Persistent Tracking — Kit claim timestamps are stored per player identifier in the database, persisting across server restarts and reconnects.
• Framework Independent — Uses gfx-lib for all framework-specific operations (player lookup, item giving, identifier retrieval), so it works with QBCore, ESX, Qbox, and others.
• Player Initialization — On player load, initializes kit cooldown records for all configured kits so new kits are immediately claimable.

Troubleshooting

Source

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