Progress

A flexible, lightweight, and animated progress bar system for FiveM. Supports 2D HUD bars, 3D in-world bars, animations, prop attachments, and control disabling.

🛠️ Core Functions

You can access the progress bar using exports.

ShowProgress (Standard 2D)

The "Fire and Forget" method. Handles the timer, animation, and cleanup automatically.

exports['ak47_lib']:ShowProgress(data, onFinish, onCancel)

Parameter	Type	Description
data	table	Configuration object (see below).
onFinish	function	(Optional) Callback when the bar reaches 100%.
onCancel	function	(Optional) Callback if the bar is cancelled (e.g., player moved or pressed X).

CancelProgress (Standard 2D)

Cancel the running 2d progress.

exports['ak47_lib']:CancelProgress()

CreateProgress (Advanced 3D)

Returns a Progress Object that you must manually control. Useful for minigames, persistent HUD elements, or skills where progress isn't time-based.

local bar = exports['ak47_lib']:CreateProgress(data)

Object Methods:

• bar.show(): Displays the bar.
• bar.update(value): Sets the percentage (0-100).
• bar.destroy(): Removes the bar immediately.

---

📦 Data Object Configuration

The data table defines how the progress bar looks and behaves.

Basic Settings

Property	Type	Default	Description
label	string	"Progress"	Text displayed on the bar.
duration	number	3000	Time in milliseconds (if not manual).
type	string	"capsule"	Visual style (see Styles below).
canCancel	boolean	false	If true, pressing X (73) cancels the action.
reverse	boolean	false	If true, the bar goes from 100% to 0%.

3D World Options

Property	Type	Default	Description
is3d	boolean	false	If true, the bar floats in the world.
coords	vector3	Player Pos	World coordinates for the bar.
distance	number	10.0	Max visibility distance for 3D bars.

State Restrictions

Property	Type	Default	Description
useWhileDead	boolean	false	Cancel if player dies?
allowSwimming	boolean	false	Cancel if player enters water?
allowFalling	boolean	false	Cancel if player falls?
allowRagdoll	boolean	false	Cancel if player gets ragdolled?

Control Disabling (disable sub-table)

Prevent player input while the bar is active.

disable = {
    move = true,    -- Disables WASD / Jumping
    mouse = true,   -- Disables Camera Look
    combat = true,  -- Disables Shooting / Aiming
    car = true,     -- Disables Entering / Exiting Vehicles
    sprint = true   -- Disables Sprinting
}

Animation (anim sub-table)

Play an animation or scenario.

anim = {
    dict = "amb@world_human_gardener_plant@male@base", 
    clip = "base", 
    flag = 49,          -- Animation flag (default 49)
    blendIn = 3.0,      -- Speed to blend in
    scenario = "WORLD_HUMAN_WELDING" -- (Alternative to dict/clip)
}

Props (prop sub-table)

Attach one or more objects to the player.

prop = {
    model = "prop_tool_wrench",
    bone = 28422,       -- Bone Index (Right Hand)
    pos = vec3(0.0, 0.0, 0.0), -- Position Offset
    rot = vec3(0.0, 0.0, 0.0)  -- Rotation Offset
}

---

🎨 Visual Styles

You can change the appearance of the progress bar by setting the type field in the data object.

Type	Description
capsule
minimal
segments
pulse
radial-smooth
radial-orbit
radial-ticks
radial-dashed

---

📝 Examples

Example 1: Basic Repair (Linear)

Simple interaction with a callback.

exports['ak47_lib']:ShowProgress({
    duration = 5000,
    label = "Repairing Engine",
    type = "capsule",
    anim = {
        dict = "mini@repair",
        clip = "fixing_a_ped"
    }
}, function()
    print("Repair Complete!")
    -- Add repair logic here
end, function()
    print("Repair Cancelled")
end)

Example 2: Medical Action (Complex)

Uses props, animations, and disables controls.

exports['ak47_lib']:ShowProgress({
    duration = 7000,
    label = "Applying Bandage",
    type = "radial-smooth",
    canCancel = true,
    disable = {
        move = true,
        combat = true
    },
    anim = {
        dict = "missheistdockssetup1clipboard@idle_a",
        clip = "idle_a",
        flag = 49
    },
    prop = {
        model = "prop_paper_bag_small",
        bone = 28422,
        pos = vec3(0.1, 0.0, 0.0),
        rot = vec3(0.0, 0.0, 0.0)
    }
}, function()
    TriggerServerEvent('medical:heal')
end)

Example 3: Manual HUD (Object Oriented)

Useful for skill checks or minigames where the script controls the percentage.

-- 1. Create the bar object
local myBar = exports['ak47_lib']:CreateProgress({
    label = "Overheating",
    type = "segments",
    manual = true, -- IMPORTANT: Disables auto-timer
    initial = 0
})

-- 2. Show it
myBar.show()

-- 3. Update it in your own loop
CreateThread(function()
    local heat = 0
    while heat < 100 do
        heat = heat + 1
        myBar.update(heat) -- Update UI
        Wait(100)
    end
    
    -- 4. Destroy it when done
    myBar.destroy()
end)

Example 4: 3D World Progress

Attach a progress bar to a specific coordinate in the world (e.g., a door being drilled).

local doorCoords = vector3(120.5, -150.2, 30.0)

exports['ak47_lib']:ShowProgress({
    duration = 10000,
    label = "Drilling Lock",
    type = "radial-orbit",
    is3d = true,        -- Enable 3D mode
    coords = doorCoords, -- Where to show the bar
    distance = 15.0,    -- Visible distance
    anim = {
        scenario = "WORLD_HUMAN_WELDING"
    }
}, function()
    print("Door Opened")
end)