Skip to main content

Library

How to Import

In order to use these utilities, you must import the Utils object which stores all helper functions. The directory from which the file is imported is different for client and server.

To import the library server-side, you must include the following line in your resource fxmanifest.lua file:

fxmanifest.lua
server_script "@px_utils/server/lib/common.lua"

To import the library client-side, you must include the following line in your resource fxmanifest.lua file:

fxmanifest.lua
client_script "@px_utils/client/lib/common.lua"

Client-side

IsPedDead

This function will return whether the ped is dead. It should be used over the native IsPedDeadOrDying function, as it checks for specific death state from px_death. An example can be seen below.

client/main.lua
local plyPed = PlayerPedId();
if Utils:IsPedDead(plyPed) then
TriggerEvent("core:notify", "You are dead :(");
end

DrawText3D

Draw text in three-dimenstional space. This function must be called in a loop.

client/main.lua
Utils:DrawText3D(x --[[int]], y --[[int]], z --[[int]], distance --[[int]], label --[[string]]);
-- x: the x-coordinate to draw at
-- y: the y-coordinate to draw at
-- z: the z-coordinate to draw at
-- distance: a distance check from your player ped to the coordinate
-- label: the text to display

Example usage:

client/main.lua
Citizen.CreateThread(function()
local plyPed = PlayerPedId();
while true do
Citizen.Wait(0);

local plyPos = GetEntityCoords(plyPed);
Utils:DrawText3D(plyPos.x, plyPos.y, plyPos.z, 3.0, "Hello World!");
end
end)

DrawMissionText

Draw native mission text.

client/main.lua
Utils:DrawMissionText(label --[[string]], duration --[[int]]);
-- label: the text to display
-- duration: time in seconds to display

DrawTimer

Draw a native countdown, must be called in a loop.

client/main.lua
Utils:DrawTimer(startTime --[[int]], duration --[[int]], x --[[int]], y --[[int]], label --[[string]]);
-- startTime: game timer at start of draw
-- duration: duration of draw in millisecond
-- x: on-screen x-coordinate of timer
-- y: on-screen y-coordinate of timer
-- label: timer label

Example usage:

client/main.lua
Citizen.CreateThread(function()
local startTime = GetGameTimer();
local duration = 5000; -- milliseconds
while GetGameTimer() - startTime < duration do
Citizen.Wait(0);
Utils:DrawTimer(startTime, duration, 1.42, 1.475, "EXAMPLE");
end
end);

DrawCountdown

Draw a native timer, must be called in a loop.

client/main.lua
Utils:DrawCountdown(startTime --[[int]], duration --[[int]], x --[[int]], y --[[int]]);
-- startTime: game timer at start of draw
-- duration: duration of draw in millisecond
-- x: on-screen x-coordinate of timer
-- y: on-screen y-coordinate of timer

Example usage:

client/main.lua
Citizen.CreateThread(function()
local startTime = GetGameTimer();
local duration = 5000; -- milliseconds
while GetGameTimer() - startTime < duration do
Citizen.Wait(0);
Utils:DrawCountdown(startTime, duration, 1.42, 1.475);
end
end);

ShowHelp

Show a native help notification.

client/main.lua
Utils:ShowHelp(label --[[string]], sound --[[bool]]);
-- label: label of help message
-- sound?: whether a sound should be played

CreateTimer

Create a native countdown timer (looped).

client/main.lua
Utils:CreateTimer(duration --[[int]]);
-- duration: time of countdown in milliseconds

CreateBar

Create a native timer bar (looped).

client/main.lua
Utils:CreateBar(duration --[[int]], label --[[string]], fRun --[[function]]);
-- duration: duration of timer bar in milliseconds
-- label: timer bar label
-- fRun?: a function which will be ran in-loop during draw

CreateBar2

Create a native timer bar (looped). This timer will show slightly above the previous one. Why is it a new function? I don't know.

client/main.lua
Utils:CreateBar2(duration --[[int]], label --[[string]], fRun --[[function]]);
-- duration: duration of timer bar in milliseconds
-- label: timer bar label
-- fRun?: a function which will be ran in-loop during draw

GetVehicleInFront

Get the vehicle in front of the player ped.

client/main.lua
local vehicle --[[int]] = Utils:GetVehicleInFront();

GetVehicleInDirection

Get the vehicle in the specified direction by casting a ray.

client/main.lua
local vehicle --[[int]] = Utils:GetVehicleInDirection(coordFrom --[[vector3]], coordTo --[[vector3]]);
-- coordFrom: starting position
-- coordTo: ending position

KeyboardInput

Create a native keyboard input prompt.

client/main.lua
local output --[[string]] = Utils:KeyboardInput(textEntry --[[string]], inputText --[[string]], maxLength --[[int]]);
-- textEntry: heading title for input
-- inputText: default input text, use "" for none
-- maxLength: max length of input in character count

LoadModel

Load a model synchronously. This function will break if the model has not loaded after five seconds.

client/main.lua
Utils:LoadModel(model --[[int]]);
-- model: model hash key to load

RequestEntityControl

Request entity control synchronously. This function will break if control is not gained after five seconds.

client/main.lua
Utils:RequestEntityControl(entity --[[int]]);
-- entity: entity to control

LoadAnimDict

Load an animation dictionary synchronously. This function will break if the dictionary has not loaded after five seconds.

client/main.lua
Utils:LoadAnimDict(animDict --[[string]]);
-- animDict: animation dictionary name

LoadPtfx

Load a partice FX dictionary synchronously. This function will break if the dictionary has not loaded after five seconds.

client/main.lua
Utils:LoadPtfx(ptfxDict --[[string]]);
-- ptfxDict: particle FX dictionary name

LoadScaleform

Load a scaleform movie synchronously. This function will break if the scaleform movie has not loaded after five seconds.

client/main.lua
Utils:LoadScaleform(dict --[[stirng]]);
-- dict: scaleform name

CommaValue

Separate a number using commas.

client/main.lua
local value --[[string]] = Utils:CommaValue(number --[[int]]);
-- number: number to format

For example:

client/main.lua
local value = Utils:CommaValue(1384732);
-- value = "1,384,732"

RemoveWhitespace

Remove any whitespace from the front and end of a string.

client/main.lua
local formatted --[[string]] = Utils:RemoveWhitespace(str --[[string]]);
-- str: string to format

WaitForNetId

Wait for a network ID to exist, has a default timeout of 1000 milliseconds.

client/main.lua
Utils:WaitForNetId(netId --[[int]], timeout --[[int]]);
-- netId: network Id to wait for
-- timeout: timeout in milliseconds

CopyTable

Create a deep copy of a table.

client/main.lua
local newTable --[[table]] = Utils:CopyTable(sourceTable --[[table]]);
-- sourceTable: table to be copied

GetVehicleSeatPedIsIn

Get the vehicle seat index that the ped is in.

client/main.lua
local seatIndex --[[int]] = Utils:GetVehicleSeatPedIsIn(vehicle --[[int]], ped --[[int]]);
-- vehicle: the target vehicle
-- ped: the target ped

Round

Round a number to the specified amount of decimal places.

client/main.lua
local rounded --[[float]] = Utils:Round(number --[[float]], numDecimalPlaces --[[int]]);
-- number: the number to be rounded
-- numDecimalPlaces: the number of decimal places to round to

EnumerateObjects

Enumerate all existing objects.

client/main.lua
for object in Utils:EnumerateObjects() do
...
end

EnumeratePeds

Enumerate all existing peds.

client/main.lua
for ped in Utils:EnumeratePeds() do
...
end

EnumerateVehicles

Enumerate all existing vehicles.

client/main.lua
for vehicle in Utils:EnumerateVehicles() do
...
end

EnumeratePickups

Enumerate all existing pickups.

client/main.lua
for pickup in Utils:EnumeratePickups() do
...
end

Server-side

CommaValue

Separate a number using commas.

server/main.lua
local value --[[string]] = Utils:CommaValue(number --[[int]]);
-- number: number to format

For example:

server/main.lua
local value = Utils:CommaValue(1384732);
-- value = "1,384,732"

RemoveWhitespace

Remove any whitespace from the front and end of a string.

server/main.lua
local formatted --[[string]] = Utils:RemoveWhitespace(str --[[string]]);
-- str: string to format

CopyTable

Create a deep copy of a table.

server/main.lua
local newTable --[[table]] = Utils:CopyTable(sourceTable --[[table]]);
-- sourceTable: table to be copied