# 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.
```lua
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.
```lua
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.
```lua
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.
```lua
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.
```lua
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.
```lua
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.
```lua
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.
```lua
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.
```lua
-- 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).
```lua
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)
```