> For the complete documentation index, see [llms.txt](https://abpstudios.gitbook.io/abp-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://abpstudios.gitbook.io/abp-docs/abp-missions/scripting-references/pmm-client-reference/game-helpers.md).

# Game Helpers

Helpers are simple logical, mathematical, etc. functions. to simplify life when developing missions.

## General

### Helper.CalculateDistance(a, b, decimals)

This function calculates the distance between two points in space.

#### Parameters

* `a`: The first point in space, specified as a vector.
* `b`: The second point in space, specified as a vector.
* `decimals` (optional): A boolean value indicating whether to return the distance with decimals (true) or as an integer (false). Default is false.

#### Return Value

* If `decimals` is true, the function returns the distance between the two points as a floating-point number.
* If `decimals` is false or not provided, the function returns the distance between the two points as an integer (rounded down).

#### Example

```lua
--- Example 1
local pointA = vector3(10.0, 5.0, 0.0)
local pointB = vector3(5.0, 2.5, 0.0)

local distance = Helper.CalculateDistance(pointA, pointB)
print(distance) -- Output: 7

--------------------
--- Example 2
local pointA = vector3(10.0, 5.0, 0.0)
local pointB = vector3(5.0, 2.5, 0.0)

local distance = Helper.CalculateDistance(pointA, pointB, true)
print(distance) -- Output: 7.1063350924

```

## Math

### Helper.Math.Round(value, numDecimalPlaces)

This function rounds a number to a specified number of decimal places.

#### Parameters

* `value`: The number to be rounded.
* `numDecimalPlaces` (optional): The number of decimal places to round to. If not provided, the function will round to the nearest integer.

#### Return Value

The function returns the rounded number.

#### Example

```lua
local number = 3.14159
local rounded = Helper.Math.Round(number, 2)
print(rounded) -- Output: 3.14
```

### Helper.Math.GroupDigits(value)

This function formats a number by grouping its digits with separators.

#### Parameters

* `value`: The number to be formatted.

#### Return Value

The function returns the formatted number as a string.

#### Example

```lua
local number = 1234567
local formatted = Helper.Math.GroupDigits(number)
print(formatted) -- Output: "1,234,567"
```

### Helper.Math.Trim(value)

This function removes leading and trailing whitespace from a string.

#### Parameters

* `value`: The string to be trimmed.

#### Return Value

The function returns the trimmed string.

#### Example

```lua
local str = "  Hello, World!  "
local trimmed = Helper.Math.Trim(str)
print(trimmed) -- Output: "Hello, World!"
```

## 3D World

### Helper.Functions.GetVehicles()

This function retrieves a list of all vehicles currently spawned in the game world.

**Parameters**

This function does not accept any parameters.

**Return Value**

* `vehicles`: A table containing the vehicle entities.

**Example**

```lua
local vehicles = Helper.Functions.GetVehicles()
for _, vehicle in ipairs(vehicles) do
    -- Do something with each vehicle entity
    -- DeleteEntity(vehicle)
end
```

### Helper.Functions.GetPlayers(onlyOtherPlayers, returnKeyValue, returnPeds)

This function retrieves a list of all players currently present in the game.

**Parameters**

* `onlyOtherPlayers` (optional): If set to `true`, only other players (excluding the local player) will be included in the list. Default is `false`.
* `returnKeyValue` (optional): If set to `true`, the function will return a table with player IDs as keys and their corresponding ped entities as values. Default is `false`.
* `returnPeds` (optional): If set to `true`, the function will return a table of ped entities instead of player IDs. Default is `false`.

**Return Value**

* `players`: A table containing either player IDs, ped entities, or key-value pairs of player ID and ped entity, based on the provided parameters.

**Example**

```lua
local players = Helper.Functions.GetPlayers()
for _, player in ipairs(players) do
    -- Do something with each player ID
end
```

```lua
local players = Helper.Functions.GetPlayers(true, false, true)
for _, ped in pairs(players) do
    -- Do something with each ped entity
end
```

### Helper.Functions.GetPlayersInArea(coords, maxDistance, onlyOtherPlayers)

This function retrieves a list of players present in a specific area.

**Parameters**

* `coords`: The coordinates of the center point of the area.
* `maxDistance`: The maximum distance from the center point to include players in the list.
* `onlyOtherPlayers` (optional): If set to `true`, only other players (excluding the local player) will be included in the list. Default is `false`.

**Return Value**

* A table containing player IDs or key-value pairs of player ID and ped entity, depending on the `returnKeyValue` parameter passed to `Helper.Functions.GetPlayers()`.

```lua
local areaCoords = vector3(0, 0, 0)
local maxDistance = 100
local playersInArea = Helper.Functions.GetPlayersInArea(areaCoords, maxDistance)
for _, player in ipairs(playersInArea) do
    -- Do something with each player ID in the area
end
```

### Helper.Functions.GetVehiclesInArea(coords, maxDistance)

This function retrieves a list of vehicles present in a specific area.

**Parameters**

* `coords`: The coordinates of the center point of the area.
* `maxDistance`: The maximum distance from the center point to include vehicles in the list.

**Return Value**

* A table containing vehicle entities.

**Example**

```lua
local areaCoords = vector3(0, 0, 0)
local maxDistance = 100
local vehiclesInArea = Helper.Functions.GetVehiclesInArea(areaCoords, maxDistance)
for _, vehicle in ipairs(vehiclesInArea) do
    -- Do something with each vehicle entity in the area
end
```

### Helper.Functions.IsSpawnPointClear(coords, maxDistance)

This function checks if a spawn point is clear of vehicles within a certain distance.

**Parameters**

* `coords`: The coordinates of the spawn point.
* `maxDistance`: The maximum distance to consider around the spawn point.

**Return Value**

* `true` if the spawn point is clear of vehicles within the specified distance, `false` otherwise.

**Example**

```lua
local spawnCoords = vector3(0, 0, 0)
local maxDistance = 5
local isClear = Helper.Functions.IsSpawnPointClear(spawnCoords, maxDistance)
if isClear then
    -- Proceed with spawning logic
else
    -- Choose a different spawn point
end
```

## Tables

### Helper.Table.GetRandomItem(t)

This function returns a random item from a table.

#### Parameters

* `t`: The table from which to retrieve a random item.

### Helper.Table.Copy(t)

This function creates a shallow copy of a table.

#### Parameters

* `t`: The table to be copied.

### Helper.Table.Contains(t, e)

This function checks if a table contains a specific element.

#### Parameters

* `t`: The table to be checked.
* `e`: The element to be searched for.

#### Return Value

* `true` if the element is found in the table, `false` otherwise.

### Helper.Table.ForEach(t, cb)

This function iterates over a table and applies a callback function to each key-value pair.

#### Parameters

* `t`: The table to iterate over.
* `cb`: The callback function to be applied to each key-value pair. It should take two parameters: the key and the value.

#### Example

```lua
local myTable = {a = 1, b = 2, c = 3}
Helper.Table.ForEach(myTable, function(key, value)
    print(key, value)
end)
```

### Helper.Table.SizeOf(t)

This function returns the number of elements in a table.

#### Parameters

* `t`: The table for which to determine the size.

#### Return Value

* The number of elements in the table.

### Helper.Table.IndexOf(t, value)

This function returns the index of the first occurrence of a value in a table.

#### Parameters

* `t`: The table to search.
* `value`: The value to search for.

#### Return Value

* The index of the first occurrence of the value in the table, or `-1` if the value is not found.

### Helper.Table.LastIndexOf(t, value)

This function returns the index of the last occurrence of a value in a table.

#### Parameters

* `t`: The table to search.
* `value`: The value to search for.

#### Return Value

* The index of the last occurrence of the value in the table, or `-1` if the value is not found.