# Crowe Progress System

Modern progress UI for RedM/VORP with action locking, cancellation, animations, props, priorities, and grouped displays.

## Features

* Multiple display types: `linear`, `boxed`, `circular`, `dots`, `spinner`, `wave`, `pulse`
* Smart helper exports for emergency/job/social/info style progress
* Optional action cancel support and control disabling
* Optional ped animation and prop attachment during active progress
* Visual-only mode for UI notifications without locking player action
* Group support and clear helpers for managing batches of progress items

***

## Installation

{% stepper %}
{% step %}

### Place resource

Place `crowe_progress` in your resources folder.
{% endstep %}

{% step %}

### server.cfg

Add `ensure crowe_progress` to your `server.cfg`.
{% endstep %}

{% step %}

### Restart

Restart server/resource.
{% endstep %}
{% endstepper %}

***

## Main Export

```lua
exports['crowe_progress']:Progress(data, callback)
```

### `data` fields

* `id` (string, optional): custom ID for the action
* `label` (string): display text
* `duration` (number): milliseconds
* `type` (string): `linear`, `boxed`, `circular`, `dots`, `spinner`, `wave`, `pulse`
* `position` (string): `center`, `top-right`, `top-left`, `bottom-right`, `bottom-left`
* `color` (string): hex fill/accent color
* `textColor` (string): optional text color
* `showPercentage` (boolean): show/hide percentage for supported types
* `canCancel` (boolean): allow cancel key
* `useWhileDead` (boolean): allow while dead
* `priority` (number): higher value renders before lower priority
* `group` (string): group id for stacked/grouped behavior
* `theme` (string): theme name
* `atm` (string): atmosphere mode (example: `night`, `golden`)
* `visualOnly` (boolean): UI only, no action lock
* `stackable` (boolean): allow starting while another action is running
* `controlDisables` (table):
  * `disableMovement` (bool)
  * `disableMouse` (bool)
  * `disableCombat` (bool)
* `animation` (table):
  * Scenario: `{ task = "WORLD_HUMAN_CROUCH_INSPECT" }`
  * Anim dict: `{ animDict = "...", anim = "...", flags = 49 }`
* `prop` (table):
  * `model`, `bone`, `coords = {x,y,z}`, `rotation = {x,y,z}`

### `callback`

* `callback(cancelled)` where `cancelled` is `true` if cancelled by key/event.

***

## Export List

* `exports['crowe_progress']:Progress(data, callback)`
* `exports['crowe_progress']:ProgressEmergency(label, duration, options)`
* `exports['crowe_progress']:ProgressJob(label, duration, options)`
* `exports['crowe_progress']:ProgressSocial(label, duration, options)`
* `exports['crowe_progress']:ProgressInfo(label, duration, options)`
* `exports['crowe_progress']:ProgressGroup(groupId, label, duration, options)`
* `exports['crowe_progress']:ClearProgress(options)`

***

## Net Events

* `crowe_progress:client:Progress` (data)
* `crowe_progress:client:ProgressEmergency` (label, duration, options)
* `crowe_progress:client:ProgressJob` (label, duration, options)
* `crowe_progress:client:ProgressSocial` (label, duration, options)
* `crowe_progress:client:ProgressInfo` (label, duration, options)
* `crowe_progress:client:ClearProgress` (options)
* `crowe_progress:client:Cancel` (id)

***

## Usage Examples (Copy/Paste)

{% stepper %}
{% step %}

### Basic linear

```lua
exports['crowe_progress']:Progress({
    label = "Checking satchel...",
    duration = 4500
}, function(cancelled)
    if not cancelled then
        print("Done")
    end
end)
```

{% endstep %}

{% step %}

### Boxed style with position

```lua
exports['crowe_progress']:Progress({
    label = "Lockpicking",
    duration = 8000,
    type = "boxed",
    position = "top-right",
    canCancel = true
})
```

{% endstep %}

{% step %}

### Circular with custom color

```lua
exports['crowe_progress']:Progress({
    label = "Thinking...",
    duration = 3500,
    type = "circular",
    color = "#FFD700"
})
```

{% endstep %}

{% step %}

### Dots loader (visual only)

```lua
exports['crowe_progress']:Progress({
    label = "Sending telegram...",
    duration = 3000,
    type = "dots",
    visualOnly = true,
    position = "bottom-left"
})
```

{% endstep %}

{% step %}

### Spinner loader

```lua
exports['crowe_progress']:Progress({
    label = "Processing order...",
    duration = 5000,
    type = "spinner",
    position = "bottom-right",
    priority = 2
})
```

{% endstep %}

{% step %}

### Wave loader

```lua
exports['crowe_progress']:Progress({
    label = "Syncing data...",
    duration = 5500,
    type = "wave",
    visualOnly = true
})
```

{% endstep %}

{% step %}

### Pulse loader + atmosphere

```lua
exports['crowe_progress']:Progress({
    label = "Heartbeat",
    duration = 7000,
    type = "pulse",
    atm = "night",
    visualOnly = true
})
```

{% endstep %}

{% step %}

### Scenario animation example (your test)

```lua
exports['crowe_progress']:Progress({
    label = "Inspecting tracks...",
    duration = 7000,
    type = "linear",
    canCancel = true,
    animation = {
        task = "WORLD_HUMAN_CROUCH_INSPECT"
    },
    controlDisables = {
        disableMovement = true,
        disableCombat = true,
        disableMouse = false
    }
}, function(cancelled)
    print(cancelled and "Cancelled" or "Finished")
end)
```

{% endstep %}

{% step %}

### Anim-dict animation example (your test)

```lua
exports['crowe_progress']:Progress({
    label = "Repairing table...",
    duration = 6500,
    type = "linear",
    canCancel = true,
    animation = {
        animDict = "amb_work@world_human_hammer@table@male_a@trans",
        anim = "base_trans_base",
        flags = 49
    },
    controlDisables = {
        disableMovement = true,
        disableCombat = true,
        disableMouse = false
    }
}, function(cancelled)
    print(cancelled and "Cancelled" or "Finished")
end)
```

{% endstep %}

{% step %}

### With attached prop

```lua
exports['crowe_progress']:Progress({
    label = "Writing notes...",
    duration = 6000,
    animation = {
        animDict = "amb_work@world_human_write_notebook@male_a@base",
        anim = "base",
        flags = 49
    },
    prop = {
        model = "p_notebook01x",
        bone = 60309,
        coords = { x = 0.10, y = 0.02, z = 0.03 },
        rotation = { x = 10.0, y = 160.0, z = 0.0 }
    }
})
```

{% endstep %}

{% step %}

### Smart helper exports

```lua
exports['crowe_progress']:ProgressEmergency("Critical failure", 8000, {
    position = "center",
    canCancel = true
})

exports['crowe_progress']:ProgressJob("Crafting item", 5000, {
    position = "top-right"
})

exports['crowe_progress']:ProgressSocial("Friend invite", 4000, {
    position = "top-left",
    type = "dots"
})

exports['crowe_progress']:ProgressInfo("Tip: Press E", 3000, {
    position = "bottom-right",
    type = "spinner"
})
```

{% endstep %}

{% step %}

### Grouped progress

```lua
exports['crowe_progress']:ProgressGroup("delivery-route", "Delivery update", 2500, {
    type = "linear",
    position = "top-right",
    visualOnly = true
})
```

{% endstep %}

{% step %}

### Clear APIs

```lua
exports['crowe_progress']:ClearProgress({ id = "my_action_id" })
exports['crowe_progress']:ClearProgress({ group = "delivery-route" })
exports['crowe_progress']:ClearProgress({ clearAll = true })
```

{% endstep %}

{% step %}

### Trigger through net event (client)

```lua
TriggerEvent('crowe_progress:client:Progress', {
    label = "Bandaging wounds...",
    duration = 5000,
    type = "linear",
    canCancel = true
})
```

{% endstep %}
{% endstepper %}

***

## Command Testing (Optional in your own script)

This resource no longer ships with built-in debug test commands.\
If you want chat/console test commands, add them in your own client script.

Example:

```lua
RegisterCommand("myprogresstest_anim", function()
    exports['crowe_progress']:Progress({
        label = "Animation test",
        duration = 7000,
        animation = { task = "WORLD_HUMAN_CROUCH_INSPECT" }
    })
end, false)
```

***

## Config Snippet

```lua
Config.Defaults = {
    Duration = 5000,
    Label = "Loading...",
    Type = "linear",
    CanCancel = true,
    UseWhileDead = false,
    ShowPercentage = true,
    Position = "center",
    Theme = "dark"
}

Config.Keys = {
    Cancel = 0x8CC9CD42 -- ESC
}
```

***

## Credits

Crowe Scripts Team


---

# 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://crowescripts.gitbook.io/documentation/about-our-scripts/redm-script-documentation/crowe-progress-system.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.