Progress

🛠 Client API Reference

The primary function to initiate a progress bar.

exports['ak47_lib']:StartProgress(data, onFinish, onCancel)
-- or
Lib47.StartProgress(data, onFinish, onCancel)

Parameters

Parameter	Type	Description
data	table	Configuration for the progress bar (see Data Object).
onFinish	function	(Optional) Callback triggered when the progress bar completes.
onCancel	function	(Optional) Callback triggered if the action is cancelled (e.g., by pressing 'X').

---

📦 Data Object

The data table accepts the following properties:

Basic Configuration

• duration (number): Time in milliseconds. Default: 3000.

• label (string): Text displayed on the UI. Default: 'Progress'.

• type (string): The visual style (see Visual Styles). Default: 'capsule'.

• canCancel (boolean): Allows the player to cancel by pressing X.

Logic & Restrictions

• useWhileDead (boolean): If true, bar won't cancel on death.

• allowSwimming (boolean): If false, bar cancels when entering water.

• allowFalling (boolean): If false, bar cancels if the player falls.

• allowRagdoll (boolean): If false, bar cancels if player is knocked over.

Animation (anim)

A sub-table to define player animations:

• dict: Animation dictionary.

• clip: Animation clip.

• flag: Animation flag (Default: 49).

• scenario: (Alternative) Name of a world scenario (e.g., WORLD_HUMAN_WELDING).

Prop Attachment (prop)

Attach an object to the player during the action:

• model: Model name or hash.

• bone: Bone index (Default: 60309 - Right Hand).

• pos: vector3(x, y, z) offset.

• rot: vector3(x, y, z) rotation.

Controls (disable)

• move: Disables WASD and jumping.

• mouse: Disables camera movement.

• combat: Disables shooting and aiming.

• car: Disables vehicle controls.

• sprint: Disables sprinting only.

---

🎨 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

---

📝 Usage Example

Basic Usage

Lib47.StartProgress({
    duration = 5000,
    label = "REPAIRING VEHICLE",
    type = "capsule"
}, function()
    -- This code runs on SUCCESS
    print("Vehicle repaired!")
end, function()
    -- This code runs on CANCEL
    print("Repair cancelled.")
end)

if Lib47.StartProgress({
    duration = 5000,
    label = "REPAIRING VEHICLE",
    type = "capsule"
}) then
    print("Vehicle repaired!")
end

Advanced Usage (Animation + Prop + Movement Disable)

Lib47.StartProgress({
    duration = 10000,
    label = "Hacking Console...",
    type = "radial-dashed",
    canCancel = true,
    anim = {
        dict = "anim@heists@ornate_bank@hack",
        clip = "hack_loop"
    },
    prop = {
        model = "prop_laptop_01a",
        pos = vec3(0.0, 0.0, 0.0),
        rot = vec3(0.0, 0.0, 0.0)
    },
    disable = {
        move = true,
        combat = true
    }
}, function()
    TriggerServerEvent('hacking:success')
end)

-- Comprehensive Example: Searching a Secure Container
exports['ak47_lib']:StartProgress({
    -- Basic UI Settings
    duration = 15000,               -- Total time: 15 seconds
    label = "SEARCHING CONTAINER",  -- UI Text
    type = "radial-orbit",          -- Visual style
    canCancel = true,               -- Player can press 'X' to stop

    -- Animation Settings
    anim = {
        dict = "anim@amb@clubhouse@tutorial@bkr_tut_ig3@", -- Animation dictionary
        clip = "machinic_loop_mechl_worker",             -- Animation clip
        blendIn = 3.0,                                   -- Fade-in speed
        blendOut = 1.0,                                  -- Fade-out speed
        flag = 49,                                       -- Upper body animation
        lockX = false,                                   -- Don't lock X axis
        lockY = false,                                   -- Don't lock Y axis
        lockZ = false                                    -- Don't lock Z axis
    },

    -- Prop Attachment (Flashlight and Crowbar)
    prop = {
        {
            model = "prop_flashlight",      -- Model hash or name
            bone = 57005,                   -- Hand bone
            pos = vec3(0.1, 0.0, 0.0),      -- Relative position
            rot = vec3(0.0, 0.0, 0.0)       -- Relative rotation
        },
        {
            model = "prop_tool_crowbar",
            bone = 18905,                   -- Left hand
            pos = vec3(0.1, 0.1, 0.0),
            rot = vec3(0.0, 0.0, 0.0)
        }
    },

    -- State Restrictions
    useWhileDead = false,    -- Cancel if player dies
    allowSwimming = false,   -- Cancel if player enters water
    allowFalling = false,    -- Cancel if player falls
    allowRagdoll = false,    -- Cancel if player is hit/ragdolled

    -- Control Disabling
    disable = {
        move = true,         -- Disable WASD/Space
        mouse = false,       -- Allow looking around
        combat = true,       -- Prevent shooting
        car = true,          -- Prevent entering/driving cars
        sprint = true        -- Force walking
    }
}, 
function()
    -- On Success:
    print("Container successfully opened!")
    TriggerServerEvent('container:giveRewards')
end, 
function()
    -- On Cancel:
    print("Action interrupted by player.")
end)