# 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)
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.menanak47.com/plugins/ak47_lib/interface/progress.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.