Math
ESX.Math reference for ESX Legacy - Round, GroupDigits, Trim, Random and GetHeadingFromCoords, with exact behavior, examples and common pitfalls.
ESX.Math holds a few number and string helpers that ESX uses for money, plates and headings. They work on client and server. In 1.16 they are implemented in esx_lib (xLib.math) and mapped onto ESX.Math.
Overview
| Resource | es_extended (implemented in esx_lib) |
| Side | Shared |
| Mapping | es_extended/shared/compat.lua |
Functions
ESX.Math.Round
ESX.Math.Round(value, numDecimalPlaces)Rounds half up (2.5 becomes 3).
| Name | Type | Description |
|---|---|---|
value | number | Number to round. Must be a number, strings raise an error. |
numDecimalPlaces | number? | Decimal places. Default 0. |
Returns: number
print(ESX.Math.Round(5.444)) -- 5
print(ESX.Math.Round(5.456, 1)) -- 5.5ESX.Round(value, numDecimalPlaces) is the same function.
ESX.Math.GroupDigits
ESX.Math.GroupDigits(value)Adds a thousands separator. The separator comes from the locale_digit_grouping_symbol entry of the active ESX locale.
| Name | Type | Description |
|---|---|---|
value | number | string | Number to format. |
Returns: string
local bank = ESX.GetAccount('bank')
ESX.ShowNotification(('Balance: $%s'):format(ESX.Math.GroupDigits(bank.money)))
-- Balance: $1,250,000ESX.Math.Trim
ESX.Math.Trim(value)Removes whitespace at the beginning and end. Spaces in the middle stay. Mostly used for GetVehicleNumberPlateText, which pads plates to 8 characters.
| Name | Type | Description |
|---|---|---|
value | string | number | Value to trim. Numbers are converted with tostring. |
Returns: string
local plate = GetVehicleNumberPlateText(vehicle) -- " ESX 12 "
print(ESX.Math.Trim(plate)) -- "ESX 12"ESX.Math.Random
ESX.Math.Random(minRange, maxRange)| Name | Type | Description |
|---|---|---|
minRange | number? | Lower bound. Default 1. |
maxRange | number? | Upper bound. Default 10. |
Returns: number, a random integer from math.random(minRange, maxRange).
local payout = ESX.Math.Random(150, 300)ESX.Math.GetHeadingFromCoords
ESX.Math.GetHeadingFromCoords(origin, target)Returns the GTA heading (0-360 degrees) that points from origin to target on the XY plane.
| Name | Type | Description |
|---|---|---|
origin | table | Plain table with x and y. |
target | table | Plain table with x and y. |
Returns: number
Both arguments are type-checked as table. Passing a vector3 raises an error. Convert vectors first, for example { x = coords.x, y = coords.y }.
local from = GetEntityCoords(ESX.PlayerData.ped)
local to = vector3(441.0, -981.0, 30.7)
local heading = ESX.Math.GetHeadingFromCoords({ x = from.x, y = from.y }, { x = to.x, y = to.y })
SetEntityHeading(ESX.PlayerData.ped, heading)More in esx_lib
xLib.math has more helpers that are not mapped to ESX.Math, for example clamp, lerp, remap, tryNumber, toInteger, hexToRGBA and toHex. Load @esx_lib/imports.lua to use them.
Related
Frequently asked questions
Independent documentation
Last updated on
Shared Functions
ESX Legacy functions available on both client and server - GetConfig, weapon lookups, ValidateType, IsValidLocaleString, GetRandomString and ESX.Await.
Table
ESX.Table reference for ESX Legacy - SizeOf, Find, Filter, Map, Clone, Concat, Join, TableContains, Sort, ToArray and more, with return values and pitfalls.