🛠️INSTALLATION

A modern and customizable progress bar system for QB-Core Framework.

1. Download the script

2. Place it in your resources folder

3. Add this to your server.cfg:

ensure janiel-progressbar

1. Import the SQL file:

CREATE TABLE IF NOT EXISTS `progress_positions` (
    `identifier` VARCHAR(50) PRIMARY KEY,
    `position_x` FLOAT NOT NULL,
    `position_y` FLOAT NOT NULL,
    `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    `updated_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

5. Replace Progress Bar Function

Navigate to qb-core/client/functions.lua and replace the existing QBCore.Functions.Progressbar function with the following code:

function QBCore.Functions.Progressbar(name, label, duration, useWhileDead, canCancel, disableControls, animation, prop, propTwo, onFinish, onCancel, icon)
    if GetResourceState('janiel-progressbar') ~= 'started' then 
        error('janiel-progressbar needs to be started in order for QBCore.Functions.Progressbar to work') 
        return false
    end
    exports['janiel-progressbar']:Progress({
        name = name:lower(),
        duration = duration,
        label = label,
        icon = icon,
        useWhileDead = useWhileDead,
        canCancel = canCancel,
        controlDisables = disableControls,
        animation = animation,
        prop = prop,
        propTwo = propTwo,
    }, function(cancelled)
        if not cancelled then
            if onFinish then
                onFinish()
            end
        else
            if onCancel then
                onCancel()
            end
        end
    end)
end 

💻 Usage

QB-Core Export Example

-- Simple Progress Bar
exports['janiel-progressbar']:Progress({
    name = "unique_name",
    duration = 5000,
    label = "Doing something...",
    useWhileDead = false,
    canCancel = true,
    controlDisables = {
        disableMovement = false,
        disableCarMovement = false,
        disableMouse = false,
        disableCombat = true,
    },
}, function(cancelled)
    if not cancelled then
        -- Do something when progress is complete
    else
        -- Do something when progress is cancelled
    end
end)

-- Progress Bar with Animation
exports['janiel-progressbar']:Progress({
    name = "unique_name",
    duration = 5000,
    label = "Doing something...",
    useWhileDead = false,
    canCancel = true,
    controlDisables = {
        disableMovement = true,
        disableCarMovement = true,
        disableMouse = false,
        disableCombat = true,
    },
    animation = {
        animDict = "missheistdockssetup1clipboard@base",
        anim = "base",
        flags = 49,
    },
}, function(cancelled)
    if not cancelled then
        -- Success
    else
        -- Cancelled
    end
end)

-- Progress Bar with Props
exports['janiel-progressbar']:Progress({
    name = "unique_name",
    duration = 5000,
    label = "Doing something...",
    useWhileDead = false,
    canCancel = true,
    controlDisables = {
        disableMovement = true,
        disableCarMovement = true,
        disableMouse = false,
        disableCombat = true,
    },
    animation = {
        animDict = "missheistdockssetup1clipboard@base",
        anim = "base",
        flags = 49,
    },
    prop = {
        model = "prop_paper_bag_small",
        bone = 18905,
        coords = { x = 0.10, y = 0.02, z = 0.08 },
        rotation = { x = -80.0, y = 0.0, z = 0.0 },
    },
}, function(cancelled)
    if not cancelled then
        -- Success
    else
        -- Cancelled
    end
end)

RegisterNetEvent('janiel-progressbar:client:progress')
AddEventHandler('janiel-progressbar:client:progress', function(data, cb)
    exports['janiel-progressbar']:Progress(data, cb)
end)

Check if Progress Bar is Active

local isActive = exports['janiel-progressbar']:progIsOpen()

Progress Bar Test Scripts for QB-Core

Instructions:

Once you load this script, you can test the following commands on the client side by typing them in the in-game console:

1. testprog1: A simple progress bar without animation or prop, where the user can cancel the process.

2. testprog2: An animated progress bar, disabling movement and combat during the animation.

3. testprog3: A progress bar with both animation and a prop attached to the player, disabling various controls.

4. testprog4: Uses the built-in QB-Core progress bar functionality, with the ability to disable combat actions.

-- Simple Progress Bar Test Command
RegisterCommand('testprog1', function()
    exports['janiel-progressbar']:Progress({
        name = "test1",
        duration = 5000, -- Duration of the progress bar in milliseconds
        label = "Simple Test...", -- Label text shown on the progress bar
        useWhileDead = false, -- Whether it can be used while the player is dead
        canCancel = true, -- Allow the player to cancel the progress bar
        controlDisables = {
            disableMovement = false, -- Disable player movement
            disableCarMovement = false, -- Disable car movement
            disableMouse = false, -- Disable mouse actions
            disableCombat = true, -- Disable combat actions during progress
        },
    }, function(cancelled)
        if not cancelled then
            QBCore.Functions.Notify('Process Completed!', 'success') -- Success notification
        else
            QBCore.Functions.Notify('Process Cancelled!', 'error') -- Error notification if cancelled
        end
    end)
end)

-- Animated Progress Bar Test Command
RegisterCommand('testprog2', function()
    exports['janiel-progressbar']:Progress({
        name = "test2",
        duration = 8000, -- Duration in milliseconds
        label = "Animated Test...", -- Label text
        useWhileDead = false, -- Can be used while dead
        canCancel = true, -- Can be cancelled by the player
        controlDisables = {
            disableMovement = true, -- Disable movement during progress
            disableCarMovement = true, -- Disable car movement
            disableMouse = false, -- Mouse actions are not disabled
            disableCombat = true, -- Disable combat
        },
        animation = {
            animDict = "missheistdockssetup1clipboard@base", -- Animation dictionary
            anim = "base", -- Animation name
            flags = 49, -- Animation flags (usually controls how the animation behaves)
        },
    }, function(cancelled)
        if not cancelled then
            QBCore.Functions.Notify('Animated Process Completed!', 'success') -- Success message
        else
            QBCore.Functions.Notify('Animated Process Cancelled!', 'error') -- Cancellation message
        end
    end)
end)

-- Prop-Based Progress Bar Test Command
RegisterCommand('testprog3', function()
    exports['janiel-progressbar']:Progress({
        name = "test3",
        duration = 10000, -- Duration in milliseconds
        label = "Prop-Based Test...", -- Label for the progress bar
        useWhileDead = false, -- Can it be used while dead?
        canCancel = true, -- Can the process be cancelled?
        controlDisables = {
            disableMovement = true, -- Disable movement during the progress
            disableCarMovement = true, -- Disable car movement
            disableMouse = false, -- Mouse actions are not disabled
            disableCombat = true, -- Disable combat actions
        },
        animation = {
            animDict = "missheistdockssetup1clipboard@base", -- Animation dictionary
            anim = "base", -- Animation name
            flags = 49, -- Animation flags
        },
        prop = {
            model = "prop_paper_bag_small", -- Model of the prop being used
            bone = 18905, -- Bone ID for attaching the prop (usually related to the player's hand)
            coords = { x = 0.10, y = 0.02, z = 0.08 }, -- Position offset for the prop
            rotation = { x = -80.0, y = 0.0, z = 0.0 }, -- Rotation for the prop
        },
    }, function(cancelled)
        if not cancelled then
            QBCore.Functions.Notify('Prop-Based Process Completed!', 'success') -- Success notification
        else
            QBCore.Functions.Notify('Prop-Based Process Cancelled!', 'error') -- Cancellation notification
        end
    end)
end)

-- QB-Core Built-in Progress Bar Test Command
RegisterCommand('testprog4', function()
    QBCore.Functions.Progressbar("test4", "QB-Core Test...", 5000, false, true, {
        disableMovement = false, -- Do not disable movement
        disableCarMovement = false, -- Do not disable car movement
        disableMouse = false, -- Do not disable mouse
        disableCombat = true, -- Disable combat actions
    }, {}, {}, {}, function() -- Done callback
        QBCore.Functions.Notify('QB-Core Process Completed!', 'success') -- Success notification
    end, function() -- Cancel callback
        QBCore.Functions.Notify('QB-Core Process Cancelled!', 'error') -- Cancellation notification
    end)
end)

ESX FRAMEWORK

Navigate to es_extended/client/functions.lua and replace the existing ESX.Progressbar function with the following code:

function ESX.Progressbar(message, length, options)
    return exports['janiel-progressbar']:Progressbar(message, length, options)
end

function ESX.CancelProgressbar()
    return exports['janiel-progressbar']:CancelProgressbar()
end

🎮 Usage

exports['janiel-progressbar']:Progressbar("Message", 5000, {
    useWhileDead = false,
    canCancel = true,
    disableMovement = false,
    disableCarMovement = false,
    disableMouse = false,
    disableCombat = true,
    animation = {
        animDict = "mini@repair",
        anim = "fixing_a_player",
        flags = 49,
    }
})