🕹️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

--- 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

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

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

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

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

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

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().

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

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

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

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.