> For the complete documentation index, see [llms.txt](https://laot7490.gitbook.io/ltbridge/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://laot7490.gitbook.io/ltbridge/utilities/utils.md).

# Utils

## Utils

General-purpose helpers — find closest player/ped/vehicle, spawn vehicles, wait for conditions.

### Functions

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>GetClosestObject</strong></td><td>Get the closest object to given coords.</td><td><a href="#getclosestobject">#getclosestobject</a></td></tr><tr><td><strong>GetClosestPed</strong></td><td>Get the closest ped to given coords (excluding players).</td><td><a href="#getclosestped">#getclosestped</a></td></tr><tr><td><strong>GetClosestPlayer</strong></td><td>Get the closest player to given coords.</td><td><a href="#getclosestplayer">#getclosestplayer</a></td></tr><tr><td><strong>GetClosestVehicle</strong></td><td>Get the closest vehicle to given coords.</td><td><a href="#getclosestvehicle">#getclosestvehicle</a></td></tr><tr><td><strong>GetPlayersInArea</strong></td><td>Get all players within a radius.</td><td><a href="#getplayersinarea">#getplayersinarea</a></td></tr><tr><td><strong>SpawnVehicle</strong></td><td>Spawns a networked vehicle at the given position.</td><td><a href="#spawnvehicle">#spawnvehicle</a></td></tr><tr><td><strong>Switch</strong></td><td>Basic switch statement for Lua.</td><td><a href="#switch">#switch</a></td></tr><tr><td><strong>WaitFor</strong></td><td>Yields the coroutine until the condition returns a non-nil value, or the timeout is reached.</td><td><a href="#waitfor">#waitfor</a></td></tr></tbody></table>

***

## GetClosestObject

Get the closest object to given coords.

{% hint style="info" %}
**Side:** Client · **Category:** Utils · **API:** `LT.Utils.GetClosestObject`
{% endhint %}

### Example

```lua
local obj, dist = LT.Utils.GetClosestObject(vector3(100.0, 200.0, 30.0), 50.0)
```

### Parameters

| Name          | Required | Description                             |
| ------------- | -------- | --------------------------------------- |
| `coords`      | No       | Coords of area (default: Player coords) |
| `maxDistance` | No       | Max search radius (default: 50.0)       |

### Returns

* `number? object, number? distance`

***

## GetClosestPed

Get the closest ped to given coords (excluding players).

{% hint style="info" %}
**Side:** Client · **Category:** Utils · **API:** `LT.Utils.GetClosestPed`
{% endhint %}

### Example

```lua
local ped, dist = LT.Utils.GetClosestPed(vector3(100.0, 200.0, 30.0), 50.0)
```

### Parameters

| Name          | Required | Description                             |
| ------------- | -------- | --------------------------------------- |
| `coords`      | No       | Coords of area (default: Player coords) |
| `maxDistance` | No       | Max search radius (default: 50.0)       |

### Returns

* `number? ped, number? distance`

***

## GetClosestPlayer

Get the closest player to given coords.

{% hint style="info" %}
**Side:** Client · **Category:** Utils · **API:** `LT.Utils.GetClosestPlayer`
{% endhint %}

### Example

```lua
local playerId, ped, dist = LT.Utils.GetClosestPlayer()
```

### Parameters

| Name          | Required | Description                             |
| ------------- | -------- | --------------------------------------- |
| `coords`      | No       | Coords of area (default: Player coords) |
| `maxDistance` | No       | Max search radius (default: 50.0)       |

### Returns

* `number? playerId, number? ped, number? distance`

***

## GetClosestVehicle

Get the closest vehicle to given coords.

{% hint style="info" %}
**Side:** Client · **Category:** Utils · **API:** `LT.Utils.GetClosestVehicle`
{% endhint %}

### Example

```lua
local veh, dist = LT.Utils.GetClosestVehicle(vector3(100.0, 200.0, 30.0), 50.0)
```

### Parameters

| Name          | Required | Description                             |
| ------------- | -------- | --------------------------------------- |
| `coords`      | No       | Coords of area (default: Player coords) |
| `maxDistance` | No       | Max search radius (default: 50.0)       |

### Returns

* `number? vehicle, number? distance`

***

## GetPlayersInArea

Get all players within a radius.

{% hint style="info" %}
**Side:** Client · **Category:** Utils · **API:** `LT.Utils.GetPlayersInArea`
{% endhint %}

### Example

```lua
local players = LT.Utils.GetPlayersInArea(vector3(100.0, 200.0, 30.0), 10.0)
```

### Parameters

| Name     | Required | Description                             |
| -------- | -------- | --------------------------------------- |
| `coords` | No       | Coords of area (default: Player coords) |
| `radius` | Yes      | number                                  |

### Returns

* `table Array of { id, ped, dist }`

***

## SpawnVehicle

Spawns a networked vehicle at the given position.

{% hint style="info" %}
**Side:** Client · **Category:** Utils · **API:** `LT.Utils.SpawnVehicle`
{% endhint %}

### Example

```lua
local result = LT.Utils.SpawnVehicle('model', 'coords', 1)
```

### Parameters

| Name      | Required | Description             |
| --------- | -------- | ----------------------- |
| `model`   | Yes      | Model name              |
| `coords`  | Yes      | Coordinates             |
| `heading` | No       | Heading. Default: `0.0` |

### Returns

* `boolean success`
* `number|nil entity`
* `number|nil netId`

***

## Switch

Basic switch statement for Lua.

{% hint style="info" %}
**Side:** Shared · **Category:** Utils · **API:** `LT.Utils.Switch`
{% endhint %}

### Example

```lua
local result = LT.Utils.Switch(2, {
    [1] = function() return 'one' end,
    [2] = function() return 'two' end,
    default = function() return 'default' end,
})
-- 'two'
```

### Parameters

| Name    | Required | Description                          |
| ------- | -------- | ------------------------------------ |
| `value` | Yes      | The value to match against the cases |
| `cases` | Yes      | table\<T                             |

### Returns

* `any|nil result The return value of the matched case function, or nil if none matched`

***

## WaitFor

Yields the coroutine until the condition returns a non-nil value, or the timeout is reached.

{% hint style="info" %}
**Side:** Shared · **Category:** Utils · **API:** `LT.WaitFor`
{% endhint %}

### Example

```lua
local ped = LT.WaitFor(function()
    local p = PlayerPedId()
    if DoesEntityExist(p) then return p end
end, 5000)
```

### Parameters

| Name       | Required | Description                                   |
| ---------- | -------- | --------------------------------------------- |
| `cb`       | Yes      | fun(): T?                                     |
| `timeout`  | No       | Timeout in milliseconds. Default: `1000`.     |
| `interval` | No       | Check interval in milliseconds. Default: `0`. |

### Returns

* `T|nil` Result from callback, or `nil` on timeout