# Entities

The `entities` module provides utility functions for detecting, filtering, and retrieving nearby or targeted game entities such as objects, peds, players, and vehicles.

***

## Accessing the Module

```lua
local ENTITIES <const> = exports.boii_utils:get("modules.entities")
```

***

## Client

### get\_nearby\_objects(coords, max\_distance)

Returns nearby objects within a certain distance.

#### Parameters

| Name          | Type      | Description                            |
| ------------- | --------- | -------------------------------------- |
| coords        | `vector3` | The center coordinates to search from. |
| max\_distance | `number`  | The maximum radius to search in.       |

#### Example

```lua
local nearby = ENTITIES.get_nearby_objects(GetEntityCoords(PlayerPedId()), 5.0)
for _, obj in pairs(nearby) do
    print("Nearby Object:", obj.entity, obj.coords)
end
```

***

### get\_nearby\_peds(coords, max\_distance)

Returns non-player peds nearby.

#### Parameters

| Name          | Type      | Description                            |
| ------------- | --------- | -------------------------------------- |
| coords        | `vector3` | The center position to search from.    |
| max\_distance | `number`  | The maximum distance to search within. |

#### Example

```lua
local peds = ENTITIES.get_nearby_peds(GetEntityCoords(PlayerPedId()), 10.0)
```

***

### get\_nearby\_players(coords, max\_distance, include\_player)

Returns player peds nearby.

#### Parameters

| Name            | Type      | Description                              |
| --------------- | --------- | ---------------------------------------- |
| coords          | `vector3` | The origin position to search from.      |
| max\_distance   | `number`  | How far out to search.                   |
| include\_player | `boolean` | Whether to include the executing player. |

#### Example

```lua
local players = ENTITIES.get_nearby_players(GetEntityCoords(PlayerPedId()), 10.0, false)
```

***

### get\_nearby\_vehicles(coords, max\_distance, include\_player\_vehicle)

Finds vehicles in proximity.

#### Parameters

| Name                     | Type      | Description                                             |
| ------------------------ | --------- | ------------------------------------------------------- |
| coords                   | `vector3` | Starting point for the check.                           |
| max\_distance            | `number`  | Max distance to scan.                                   |
| include\_player\_vehicle | `boolean` | Whether to include the player’s vehicle in the results. |

#### Example

```lua
local vehicles = ENTITIES.get_nearby_vehicles(GetEntityCoords(PlayerPedId()), 20.0, false)
```

***

### get\_closest\_object(coords, max\_distance)

Returns the closest object.

#### Parameters

| Name          | Type      | Description           |
| ------------- | --------- | --------------------- |
| coords        | `vector3` | Where to search from. |
| max\_distance | `number`  | Search radius.        |

#### Example

```lua
local object, coords = ENTITIES.get_closest_object(GetEntityCoords(PlayerPedId()), 5.0)
```

***

### get\_closest\_ped(coords, max\_distance)

Returns the nearest non-player ped.

#### Parameters

| Name          | Type      | Description            |
| ------------- | --------- | ---------------------- |
| coords        | `vector3` | Where to begin search. |
| max\_distance | `number`  | Distance limit.        |

#### Example

```lua
local ped, coords = ENTITIES.get_closest_ped(GetEntityCoords(PlayerPedId()), 10.0)
```

***

### get\_closest\_player(coords, max\_distance, include\_player)

Finds the nearest player ped.

#### Parameters

| Name            | Type      | Description                       |
| --------------- | --------- | --------------------------------- |
| coords          | `vector3` | Origin point.                     |
| max\_distance   | `number`  | Search distance.                  |
| include\_player | `boolean` | Include calling player in search. |

#### Example

```lua
local player, ped, coords = ENTITIES.get_closest_player(GetEntityCoords(PlayerPedId()), 10.0, false)
```

***

### get\_closest\_vehicle(coords, max\_distance, include\_player\_vehicle)

Returns the closest vehicle entity.

#### Parameters

| Name                     | Type      | Description                                       |
| ------------------------ | --------- | ------------------------------------------------- |
| coords                   | `vector3` | Coordinates to center the search on.              |
| max\_distance            | `number`  | Max scan distance.                                |
| include\_player\_vehicle | `boolean` | Whether to consider the player’s current vehicle. |

#### Example

```lua
local veh, coords = ENTITIES.get_closest_vehicle(GetEntityCoords(PlayerPedId()), 10.0, false)
```

***

### get\_entities\_in\_front\_of\_player(fov, distance)

Checks for an entity in the player’s FOV.

#### Parameters

| Name     | Type     | Description                         |
| -------- | -------- | ----------------------------------- |
| fov      | `number` | The angle cone to check in degrees. |
| distance | `number` | Max range to scan forward.          |

#### Example

```lua
local entity = ENTITIES.get_entities_in_front_of_player(45, 10.0)
```

***

### get\_target\_ped(player\_ped, fov, distance)

Finds a valid non-player ped in front or the nearest.

#### Parameters

| Name        | Type     | Description               |
| ----------- | -------- | ------------------------- |
| player\_ped | `number` | The calling player’s ped. |
| fov         | `number` | Angle to check forward.   |
| distance    | `number` | Maximum range to search.  |

#### Example

```lua
local ped, coords = ENTITIES.get_target_ped(PlayerPedId(), 60.0, 10.0)
```


---

# 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://docs.boii.dev/old-docs/boii_utils/api/entities.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.