110 online 3 members  + Join RP Base  +
FreeScriptQBoxQBCoreESX

keep-progressbar

by swkeep  ·  version 2025.09.25  ·  updated 3 days ago

No reviews yet

Downloads
0
Reviews
0
Size
254 KB
Code check
Clean
Licence
GPL-3.0
Released
Nov 2026

A flexible, progress bar system for FiveM

keep-progressbar
keep-progressbar
A flexible, progress bar system for FiveM.
Supports animations, props, stages/minigames, cancel/death monitoring, networked props with blacklist protection, and more.
Features
  • Multi-stage progress with optional skill-check / minigame support
  • Animation helper with synchronized scenes and entity attachments
  • Automatic cleanup server and client side
  • Prop support: multiple props per action
  • Customizable cancel button
  • Animation hooks
  • Themes
Installation1. Download
Clone or download this repository into your FiveM resources folder.
1.1. QBCore
If using QBCore, move/delete the progressbar resource from your [standalone] and place keep-progressbar in [standalone]

resources/[standalone]/keep-progressbar

1.2. ESX
If using ESX, move/delete the esx_progressbar resource from your [core] and place keep-progressbar in [core]

resources/[core]/keep-progressbar

1.3 ox_lib
To integrate progress bars made for ox\_lib:

  1. First open:

   ox_lib/resource/interface/progress.lua

  1. Make a backup of the file.
  2. Delete all contents, then replace them with:

    function lib.progressBar(data)
        return exports['keep-progressbar']:ox_lib_progressBar(data)
    end

    function lib.progressCircle(data)
        return exports['keep-progressbar']:ox_lib_progressBar(data)
    end

    function lib.cancelProgress()
        exports['keep-progressbar']:ox_lib_cancelProgress()
    end

    function lib.progressActive()
        exports['keep-progressbar']:ox_lib_progressActive()
    end

  1. Ensure it's loading before ox_lib and it's placed at [standalont].

    resources/[standalone]/keep-progressbar

    ensure keep-progressbar
    ensure ox_lib

UsageBasic Usage
exports['keep-progressbar']:Start({
    duration = 5000,
    label = "Loading Crate",
    icon = "fa-solid fa-box",
    canCancel = true,
    useWhileDead = false,
    controlDisables = {
        disableMovement = true,
        disableCombat = true,
    },
    animation = {
        animDict = "anim@heists@box_crate@load",
        anim = "load_box",
        duration = 5000,
        lockX = true,
        lockY = false,
        lockZ = true,
    },
    prop = {
        model = "prop_crate_01a",
        bone = 28422,
        coords = vec3(0.0, 0.0, 0.0),
        rotation = vec3(0.0, 0.0, 0.0),
    }
}, function(cancelled)
    if not cancelled then
        print("✅ completed")
    else
        print("❌ Cancelled.")
    end
end)

Multi-stage progress
exports['keep-progressbar']:Start({
    label = "Opening Crate",
    icon = "fa-solid fa-box-open",
    animation = {
        task = "WORLD_HUMAN_CLIPBOARD"
    },
    canCancel = true,
    controlDisables = { disableMovement = true, disableCombat = true },
    stages = {
        { message = "Breaking lock...", duration = 3000 },
        { message = "Opening door...", duration = 2000 },
    },
    props = {
        {
            model = "prop_ld_case_01",
            bone = 57005,
            coords = vec3(0, 0, 0),
            rotation = vec3(0, 0, 0),
        },
    }
}, function(cancel, result)
    if not cancel then
        print("✅ Crate opened!")
    else
        print("❌ Aborted opening crate.")
    end
end)

📦 Examples
I’ve provided a bunch of examples for different features in lua/examples.lua
**Start**Options
Key, Type, Description

duration, number(ms), Total duration if no stages are used
label, string, Title of progress window
icon, string, Icon (FontAwesome)
useWhileDead, boolean, Allow while dead
canCancel, boolean, Whether player can progress cancel or not
controlDisables, table, e.g. { disableMovement=true, disableCarMovement=true, disableMouse=false, disableCombat=true }
theme, string, Optional theme name
position, string, UI position (e.g. center-top)
offset, vec3, Progress bar offset
prop, table, Single prop attached during progress
propTwo, table, Single prop attached during progress
props, table[], Array of props
animation, table, Single animation
animations, table[], Array of animations
stages, table[], Array of stages

Prop, PropTwo, Props:

Field, Type, Description

model, string, Model name
bone, number, Bone index
coords, vector3, Offset coordinates
rotation, vector3, Rotation

prop = {
    model = "prop_police_phone",
    bone = 28422,
    coords = vector3(0.00, 0.0, 0.0),
    rotation = vector3(0.0, 0.0, 0.0),
},
propTwo = {
    model = "prop_police_phone",
    bone = 28422,
    coords = vector3(0.00, 0.0, 0.0),
    rotation = vector3(0.0, 0.0, 0.0),
},

Or simply using an array

props = {
    {
        model = "prop_police_phone",
        bone = 28422,
        coords = vector3(0.00, 0.0, 0.0),
        rotation = vector3(0.0, 0.0, 0.0),
    }
}

Animation:

Field, Type, Description

animDict, string, Animation dictionary
anim, string, Animation name
flags, number, Animation flags
duration, number, Duration in ms
blendIn, number, Blend-in speed
blendOut, number, Blend-out speed
onStart, func, Called at start
onTick, func, Called during, with frame time
onFinish, func, Called after

Single animation

animation = {
    animDict = "anim@heists@humane_labs@emp@hack_door",
    anim = "hack_loop",
},

Array of animations

```lua

animations = {
{
animDict = "anim@heists@humane_labs@emp@hack_door",
anim = "hack_intro",
flags = 1,
duration = 2500,
blendIn = 3.0,
blendOut = 3.0,
},
{
animDict = "anim@heists@humane_labs@emp@hack_door",
anim = "hack_loop",
flags = 1,
duration = 3000,
blendIn = 3.0,
blendOut = 3.0,
},
{
animDict = "anim@heists@humane_labs@emp@hack_door",
anim = "hack_outro",
flags = 1,
duration = 2000,

…