# Scaleform (/docs/es_extended/client/modules/scaleform)

`ESX.Scaleform` shows a few common GTA V scaleform screens with one call and gives you two helpers to work with any other scaleform movie. Use it for big on-screen announcements such as "WASTED"-style shards, a news ticker or a warning popup.

## Overview [#overview]

| | |
|---|---|
| Resource | `es_extended` (implemented in `esx_lib` as `xLib.scaleform`) |
| Side | Client |

The four `Show*` functions **block** the calling thread for `sec` seconds while they draw the movie every frame, then release it.

## Functions [#functions]

### ESX.Scaleform.ShowFreemodeMessage [#esxscaleformshowfreemodemessage]

```lua
ESX.Scaleform.ShowFreemodeMessage(title, msg, sec)
```

Shows the big centered shard of the `MP_BIG_MESSAGE_FREEMODE` movie.

| Name | Type | Description |
|---|---|---|
| `title` | `string` | Large title. |
| `msg` | `string` | Subtitle. |
| `sec` | `number` | Duration in seconds. |

**Returns:** nothing

```lua
CreateThread(function()
    ESX.Scaleform.ShowFreemodeMessage('~g~HEIST COMPLETE', 'You earned $50,000', 5)
end)
```

### ESX.Scaleform.ShowBreakingNews [#esxscaleformshowbreakingnews]

```lua
ESX.Scaleform.ShowBreakingNews(title, msg, bottom, sec)
```

Shows the Weazel News `BREAKING_NEWS` overlay.

| Name | Type | Description |
|---|---|---|
| `title` | `string` | Scrolling ticker text. |
| `msg` | `string` | Main headline. |
| `bottom` | `string` | Line under the headline. |
| `sec` | `number` | Duration in seconds. |

**Returns:** nothing

```lua
CreateThread(function()
    ESX.Scaleform.ShowBreakingNews('Pacific Standard robbed', 'BANK ROBBERY', 'Police on scene', 10)
end)
```

### ESX.Scaleform.ShowPopupWarning [#esxscaleformshowpopupwarning]

```lua
ESX.Scaleform.ShowPopupWarning(title, msg, bottom, sec)
```

Shows the full-screen `POPUP_WARNING` alert.

| Name | Type | Description |
|---|---|---|
| `title` | `string` | Title. |
| `msg` | `string` | Message. |
| `bottom` | `string` | Footer text. |
| `sec` | `number` | Duration in seconds. |

**Returns:** nothing

```lua
CreateThread(function()
    ESX.Scaleform.ShowPopupWarning('Server restart', 'The server restarts in 5 minutes.', 'Please finish your roleplay.', 8)
end)
```

### ESX.Scaleform.ShowTrafficMovie [#esxscaleformshowtrafficmovie]

```lua
ESX.Scaleform.ShowTrafficMovie(sec)
```

Plays the `TRAFFIC_CAM` movie full screen.

| Name | Type | Description |
|---|---|---|
| `sec` | `number` | Duration in seconds. |

**Returns:** nothing

## Utils [#utils]

### ESX.Scaleform.Utils.RequestScaleformMovie [#esxscaleformutilsrequestscaleformmovie]

```lua
ESX.Scaleform.Utils.RequestScaleformMovie(movie)
```

Requests a scaleform movie and waits until it is loaded. There is no timeout, so only use valid movie names.

| Name | Type | Description |
|---|---|---|
| `movie` | `string` | Movie name, for example `MIDSIZED_MESSAGE`. |

**Returns:** `number` scaleform handle.

### ESX.Scaleform.Utils.RunMethod [#esxscaleformutilsrunmethod]

```lua
ESX.Scaleform.Utils.RunMethod(scaleform, methodName, returnValue, ...)
```

Calls a method on a scaleform. If you pass a movie name instead of a handle, the movie is loaded first. Arguments are pushed by type: integers, floats, strings and booleans.

| Name | Type | Description |
|---|---|---|
| `scaleform` | `number \| string` | Handle or movie name. |
| `methodName` | `string` | Method to call. |
| `returnValue` | `boolean?` | When `true`, end with `EndScaleformMovieMethodReturnValue`. |
| `...` | `number \| string \| boolean` | Method arguments. |

**Returns:** the scaleform handle, plus the return value handle when `returnValue` is `true`. You must release the movie yourself with `SetScaleformMovieAsNoLongerNeeded`.

```lua
CreateThread(function()
    local scaleform = ESX.Scaleform.Utils.RunMethod('MIDSIZED_MESSAGE', 'SHOW_SHARD_MIDSIZED_MESSAGE', false, 'Shift started', 'Drive to the depot')
    local endTime = GetGameTimer() + 4000

    while GetGameTimer() < endTime do
        DrawScaleformMovieFullscreen(scaleform, 255, 255, 255, 255, 0)
        Wait(0)
    end

    SetScaleformMovieAsNoLongerNeeded(scaleform)
end)
```

<Callout type="info">
Floats and integers are different in Lua 5.4. Write `500.0` when a scaleform method expects a float and `500` when it expects an integer.
</Callout>

## Related [#related]

- [Client UI](/docs/es_extended/client/ui)
- [Streaming](/docs/es_extended/client/modules/streaming)
- [esx_lib](/docs/core/esx_lib)
- [FiveM native reference](https://docs.fivem.net/natives/)