Integration - Legacy Progressbar | Legacy Scripts Docs

Client Exports#

Start#

Starts a progress bar. Returns true if the progress completed, or false if it was cancelled or interrupted.

local success = exports['legacy-progressbar']:Start(data)

This is a yielding call -- the script waits until the progress bar finishes or is cancelled before continuing.

Data Table Parameters

Parameter	Type	Required	Description
`label`	string	Yes	Text displayed above the progress bar
`duration`	number	Yes	Duration in milliseconds
`canCancel`	boolean	No	Whether the player can cancel with the cancel keybind (default: `false`)
`icon`	string	No	FontAwesome 6 icon class (e.g. `'fa-solid fa-wrench'`)
`color`	string	No	Bar color override in hex (default: accent color from legacy-lib)
`useWhileDead`	boolean	No	Allow progress while dead (default: `false`)
`allowRagdoll`	boolean	No	Allow progress during ragdoll (default: `false`)
`allowCuffed`	boolean	No	Allow progress while cuffed (default: `false`)
`allowFalling`	boolean	No	Allow progress while falling (default: `false`)
`allowSwimming`	boolean	No	Allow progress while swimming (default: `false`)
`anim`	table	No	Animation to play during progress (see Animation Options)
`prop`	table	No	Prop(s) to attach during progress (see Prop Options)
`disable`	table	No	Controls to disable during progress (see Disable Options)

Animation Options

The anim table supports either a dictionary animation or a scenario:

Dictionary Animation:

Parameter	Type	Required	Description
`anim.dict`	string	Yes	Animation dictionary name
`anim.clip`	string	Yes	Animation clip name
`anim.blendIn`	number	No	Blend-in speed (default: `3.0`)
`anim.blendOut`	number	No	Blend-out speed (default: `1.0`)
`anim.duration`	number	No	Animation duration in ms, `-1` for loop (default: `-1`)
`anim.flag`	number	No	Animation flag (default: `49`)
`anim.playbackRate`	number	No	Playback rate (default: `0`)
`anim.lockX`	boolean	No	Lock X position
`anim.lockY`	boolean	No	Lock Y position
`anim.lockZ`	boolean	No	Lock Z position

Scenario:

Parameter	Type	Required	Description
`anim.scenario`	string	Yes	Scenario name (e.g. `'PROP_HUMAN_BUM_BIN'`)
`anim.playEnter`	boolean	No	Play the enter animation (default: `true`)

Prop Options

The prop field can be a single prop table or an array of prop tables. Props are synced to all players via state bags.

Parameter	Type	Required	Description
`prop.model`	string	Yes	Prop model name or hash
`prop.bone`	number	No	Ped bone index to attach to (default: `60309` / right hand)
`prop.pos`	vector3	Yes	Position offset `{x, y, z}`
`prop.rot`	vector3	Yes	Rotation offset `{x, y, z}`
`prop.rotOrder`	number	No	Rotation order (default: `0`)

Disable Options

The disable table controls which player inputs are blocked during progress:

Parameter	Type	Description
`disable.mouse`	boolean	Disable mouse look/aim
`disable.move`	boolean	Disable movement (WASD) and sprint
`disable.sprint`	boolean	Disable sprint only (ignored if `move` is true)
`disable.car`	boolean	Disable vehicle controls (steering, acceleration, braking, exit)
`disable.combat`	boolean	Disable combat (aiming and firing)

Cancel#

Cancel the currently active progress bar.

exports['legacy-progressbar']:Cancel()

IsActive#

Check if a progress bar is currently running.

local active = exports['legacy-progressbar']:IsActive()

Returns true if a progress bar is active, false otherwise.

Server Export: TriggerProgress#

Start a progress bar on a specific player from server-side.

exports['legacy-progressbar']:TriggerProgress(source, data)

Parameter	Type	Required	Description
`source`	number	Yes	Player server ID
`data`	table	Yes	Progress data table (same fields as the client Start export)

Note: The server export triggers the progress bar on the client but does not return a completion result. Use client-side exports when you need to know the outcome.

Examples#

Basic Progress Bar#

local success = exports['legacy-progressbar']:Start({
    label = 'Searching...',
    duration = 5000,
})

if success then
    print('Search completed')
else
    print('Search was cancelled')
end

With Animation and Controls Disabled#

local success = exports['legacy-progressbar']:Start({
    label = 'Repairing Vehicle',
    duration = 10000,
    canCancel = true,
    icon = 'fa-solid fa-wrench',
    anim = {
        dict = 'mini@repair',
        clip = 'fixing_a_player',
    },
    disable = {
        move = true,
        combat = true,
    },
})

With Prop Attachment#

local success = exports['legacy-progressbar']:Start({
    label = 'Drilling...',
    duration = 8000,
    icon = 'fa-solid fa-screwdriver',
    anim = {
        dict = 'anim@heists@fleeca_bank@drilling',
        clip = 'drill_straight_idle',
    },
    prop = {
        model = 'hei_prop_heist_drill',
        bone = 57005,
        pos = { x = 0.14, y = 0.0, z = -0.01 },
        rot = { x = 90.0, y = 0.0, z = 0.0 },
    },
    disable = {
        move = true,
        combat = true,
    },
})

Multiple Props#

local success = exports['legacy-progressbar']:Start({
    label = 'Eating...',
    duration = 5000,
    prop = {
        {
            model = 'prop_cs_burger_01',
            bone = 18905,
            pos = { x = 0.13, y = 0.05, z = 0.02 },
            rot = { x = -50.0, y = 16.0, z = 60.0 },
        },
        {
            model = 'prop_food_bag1',
            bone = 57005,
            pos = { x = 0.1, y = -0.03, z = 0.0 },
            rot = { x = 0.0, y = 0.0, z = 0.0 },
        },
    },
    anim = {
        dict = 'mp_player_inteat@burger',
        clip = 'mp_player_int_eat_burger_fp',
        flag = 49,
    },
})

With Scenario#

local success = exports['legacy-progressbar']:Start({
    label = 'Fishing...',
    duration = 15000,
    canCancel = true,
    icon = 'fa-solid fa-fish',
    anim = {
        scenario = 'WORLD_HUMAN_STAND_FISHING',
        playEnter = true,
    },
})

Custom Color#

local success = exports['legacy-progressbar']:Start({
    label = 'Hacking...',
    duration = 12000,
    color = '#8B5CF6',
    icon = 'fa-solid fa-terminal',
    disable = {
        move = true,
        combat = true,
        mouse = true,
    },
})

Server-Side Trigger#

-- From a server script
exports['legacy-progressbar']:TriggerProgress(source, {
    label = 'Processing...',
    duration = 3000,
    icon = 'fa-solid fa-gear',
})

Interrupt Conditions#

The progress bar is automatically cancelled if any of the following occur (unless the corresponding allow* flag is set to true):

Player dies (useWhileDead)
Player enters ragdoll state (allowRagdoll)
Player is cuffed (allowCuffed)
Player is falling (allowFalling)
Player is swimming (allowSwimming)

Inventory Busy State#

While a progress bar is active, LocalPlayer.state.invBusy is set to true. This is automatically cleared when the progress completes or is cancelled. This state is commonly used by inventory systems to prevent item usage during actions.