# Configuration

`MSK Progress Bar` is configured through export arguments and a simple locale setting.

### Configuration File

* `data/config.lua` — localization configuration

### Localization

File: `data/config.lua`

```lua
Locale = 'en' -- 'en' or 'pl'
```

Defines which language should be used.

Supported values:

* `en`
* `pl`

Example:

```
Locale = 'pl'
```

***

### Main Export

The main export used by this resource is:

```lua
exports['msk_progressbar']:StartProgressBar(data)
```

This export starts a new progress bar using the provided settings.

***

### Basic Structure

```lua
exports['msk_progressbar']:StartProgressBar({
    text     = 'Cleaning...',
    duration = 10,
    icon     = 'fa-solid fa-broom',
    run      = false,

    OnStart = function()
    end,

    OnComplete = function(data)
    end,

    OnStop = function(data)
    end,

    OnUpdate = function(currentValue)
    end,
})
```

***

### Parameters

#### `text`

Defines the label shown on the progress bar.

```lua
text = 'Cleaning...'
```

This value is required.

***

#### `duration`

Defines how long the progress bar should run in seconds.

```lua
duration = 10
```

This value is required.

***

#### `icon`

Defines the Font Awesome icon shown on the progress bar.

```lua
icon = 'fa-solid fa-broom'
```

This value is optional.

If no icon is provided, the resource uses its default spinner icon.

***

#### `run`

Defines whether the player can cancel the progress bar with `X`.

```lua
run = true
```

Supported values:

* `false` — the progress bar cannot be cancelled
* `true` — the player can press `X` to cancel it

***

### Callbacks

#### `OnStart`

Runs immediately when the progress bar starts.

```lua
OnStart = function()
    -- fires immediately when the bar starts
end
```

***

#### `OnComplete`

Runs when the progress bar finishes naturally.

```lua
OnComplete = function(data)
    -- fires when the bar finishes naturally
end
```

Use this callback to trigger actions after a successful timed process.

***

#### `OnStop`

Runs when the progress bar is cancelled.

```lua
OnStop = function(data)
    -- fires when the player cancels
end
```

This callback only applies when `run = true` or when the progress bar is cancelled programmatically.

***

#### `OnUpdate`

Runs continuously while the progress bar is active.

```lua
OnUpdate = function(currentValue)
    -- fires every UI tick with the current progress value
end
```

`currentValue` is a progress value between:

* `0.0`
* `1.0`

This can be used if you want to track or react to progress updates in real time.

***

### Minimal Example

```lua
exports['msk_progressbar']:StartProgressBar({
    text     = 'Searching...',
    duration = 5,
    icon     = 'fa-solid fa-magnifying-glass',
    run      = true,

    OnComplete = function()
        TriggerEvent('my_resource:giveItem')
    end,

    OnStop = function()
        Core.ShowNotification('~r~Action cancelled')
    end,
})
```

***

### Cancel Export

You can also stop the active progress bar manually with:

```lua
exports['msk_progressbar']:CancelProgressbar()
```

This will cancel the active progress bar and trigger the `OnStop` callback.

***

### Notes

* Only one progress bar can be active at a time
* Starting a new progress bar while one is already active will do nothing
* `run = false` means the player cannot cancel the progress bar
* `run = true` allows the player to cancel with `X`
* `CancelProgressbar()` stops the bar programmatically


---

# 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://mskscripts.gitbook.io/mskscripts/scripts/progress-bar/configuration.md?ask=<question>
```

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.