> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atlasscripts.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Progress

> A blocking progress bar with optional prop, animation, and movement lock — all cleaned up automatically.

`Bridge.Progress` shows a timed progress bar and **blocks** until it fills or is cancelled. Use it for any timed action — reeling in a fish, picking a lock, washing a car. It can attach a prop, play an animation or scenario, and lock movement for the duration, then tear all of that down for you when the bar ends.

## Availability

Client only. Call it inside a thread, command, or event callback — it yields.

```lua theme={null}
local completed = Bridge.Progress(opts)   -- boolean
Bridge.Progress.Cancel()                   -- force-cancel from elsewhere
Bridge.Progress.IsActive()                 -- boolean (always false on the own renderer)
```

## Signature

`Bridge.Progress(opts)` — the call blocks and returns whether the bar completed.

<ParamField path="duration" type="number" required>
  How long the bar takes to fill, in milliseconds.
</ParamField>

<ParamField path="label" type="string">
  The text shown beside the bar.
</ParamField>

<ParamField path="icon" type="string">
  An optional leading icon.
</ParamField>

<ParamField path="canCancel" type="boolean" default="false">
  When true, the player can cancel (a close button appears); the call then returns `false`.
</ParamField>

<ParamField path="disableControls" type="boolean" default="false">
  Locks movement, sprint, jump, and attack for the duration.
</ParamField>

<ParamField path="prop" type="table">
  A single prop to attach for the duration: `{ model, bone?, pos?, rot? }`. `bone` defaults to `60309` (right hand); `pos`/`rot` are `{ x, y, z }` offsets.
</ParamField>

<ParamField path="props" type="table[]">
  Multiple props, each shaped like `prop` above. Use instead of `prop` when you need more than one.
</ParamField>

<ParamField path="anim" type="table">
  An animation to play: `{ dict, clip, flag?, blendIn?, blendOut?, duration? }`. `flag` defaults to `49`.
</ParamField>

<ParamField path="scenario" type="string">
  A scenario to play instead of `anim`, e.g. `'WORLD_HUMAN_STAND_FISHING'`.
</ParamField>

## Returns

<ResponseField name="completed" type="boolean">
  `true` if the bar filled to 100%, `false` if the player (or a `Bridge.Progress.Cancel()` call) cancelled it.
</ResponseField>

The props, animation/scenario, and control lock are cleaned up automatically whether the bar completes or cancels.

## Examples

<CodeGroup>
  ```lua Basic theme={null}
  CreateThread(function()
      local ok = Bridge.Progress({ label = 'Searching…', duration = 3000, canCancel = true })
      if ok then findLoot() end
  end)
  ```

  ```lua With prop + animation theme={null}
  local ok = Bridge.Progress({
      label           = 'Reeling in…',
      duration        = 4000,
      canCancel       = true,
      disableControls = true,
      prop = {
          model = 'prop_fishing_rod_01',
          bone  = 18905,
          pos   = { x = 0.1, y = 0.0, z = 0.0 },
          rot   = { x = 80.0, y = 0.0, z = 0.0 },
      },
      anim = { dict = 'amb@world_human_stand_fishing@idle_a', clip = 'idle_c', flag = 49 },
  })
  if ok then catchFish() end
  ```

  ```lua Scenario instead of anim theme={null}
  Bridge.Progress({
      label    = 'Fixing the engine…',
      duration = 6000,
      scenario = 'WORLD_HUMAN_VEHICLE_MECHANIC',
  })
  ```
</CodeGroup>

<Warning>
  `Bridge.Progress` yields. Always call it inside a `CreateThread`, command, or event callback — never at file top level.
</Warning>

<Tip>
  The bar fill uses the player's theme accent automatically. Set `atlas:ui "ox"` (or `atlas:ui:progress "ox"`) to render the same call through ox\_lib's progress bar instead.
</Tip>