Entities

The utils.entities module contains a variety of useful functions for use within the game world.

Functions

get_nearby_objects()

Gets a list of objects nearby specified coords and within radius.

Function

local function get_nearby_objects(coords, max_distance)
    local objects = GetGamePool('CObject')
    local nearby = {}
    local count = 0
    max_distance = max_distance or 2.0
    for i = 1, #objects do
        local object = objects[i]
        local object_coords = GetEntityCoords(object)
        local distance = #(coords - object_coords)
        if distance < max_distance then
            count = count + 1
            nearby[count] = {
                object = object,
                coords = object_coords
            }
        end
    end
    return nearby
end

exports('entities_get_nearby_objects', get_nearby_objects)
utils.entities.get_nearby_objects = get_nearby_objects

Example

--- Returns all objects within 10.0 of coords.
local objects = utils.entities.get_nearby_objects({x = 0.0, y = 0.0, z = 0.0}, 10.0)

get_nearby_peds()

Gets a list of none player peds nearby specified coords and within radius.

Function

local function get_nearby_peds(coords, max_distance)
    local peds = GetGamePool('CPed')
    local nearby = {}
    local count = 0
    max_distance = max_distance or 2.0
    for i = 1, #peds do
        local ped = peds[i]
        if not IsPedAPlayer(ped) then
            local ped_coords = GetEntityCoords(ped)
            local distance = #(coords - ped_coords)
            if distance < max_distance then
                count = count + 1
                nearby[count] = {
                    ped = ped,
                    coords = ped_coords
                }
            end
        end
    end
    return nearby
end

exports('entities_get_nearby_peds', get_nearby_peds)
utils.entities.get_nearby_peds = get_nearby_peds

Example

--- Returns all peds within 10.0 of coords.
local peds = utils.entities.get_nearby_peds({x = 0, y = 0, z = 0}, 10.0)

get_nearby_players()

Gets a list of player peds nearby a specified coords and within radius, optionally include the players ped.

Function

local function get_nearby_players(coords, max_distance, include_player)
    local players_list = GetActivePlayers()
    local nearby = {}
    local count = 0
    max_distance = max_distance or 2.0
    for i = 1, #players_list do
        local player_id = players_list[i]
        if player_id ~= PlayerId() or include_player then
            local player_ped = GetPlayerPed(player_id)
            local player_coords = GetEntityCoords(player_ped)
            local distance = #(coords - player_coords)
            if distance < max_distance then
                count = count + 1
                nearby[count] = {
                    id = player_id,
                    ped = player_ped,
                    coords = player_coords
                }
            end
        end
    end
    return nearby
end

exports('entities_get_nearby_players', get_nearby_players)
utils.entities.get_nearby_players = get_nearby_players

Example

--- Returns all player peds within 10.0 of coords and ignores player ped
local players = utils.entities.get_nearby_players({x = 0, y = 0, z = 0}, 10.0, false)

--- Returns all player peds within 10.0 of coords and includes player ped
local players = utils.entities.get_nearby_players({x = 0, y = 0, z = 0}, 10.0, true)

get_nearby_vehicles()

Gets a list of vehicles nearby a specified coords and within radius, optionally include the players vehicle.

Function

local function get_nearby_vehicles(coords, max_distance, player_vehicle)
    local vehicles = GetGamePool('CVehicle')
    local nearby = {}
    local count = 0
    max_distance = max_distance or 2.0
    for i = 1, #vehicles do
        local vehicle = vehicles[i]
        if not IsPedInVehicle(PlayerPedId(), vehicle, true) or player_vehicle then
            local vehicle_coords = GetEntityCoords(vehicle)
            local distance = #(coords - vehicle_coords)
            if distance < max_distance then
                count = count + 1
                nearby[count] = {
                    vehicle = vehicle,
                    coords = vehicle_coords
                }
            end
        end
    end
    return nearby
end

exports('entities_get_nearby_vehicles', get_nearby_vehicles)
utils.entities.get_nearby_vehicles = get_nearby_vehicles

Example

--- Returns all vehicles within 10.0 of coords and ignores players vehicle
local vehicles = utils.entities.get_nearby_vehicles({x = 0, y = 0, z = 0}, 10.0, false)

--- Returns all vehicles within 10.0 of coords and includes players vehicle
local vehicles = utils.entities.get_nearby_vehicles({x = 0, y = 0, z = 0}, 10.0, true)

get_closest_object()

Gets closest object to specified coords within radius.

Function

local function get_closest_object(coords, max_distance)
    local objects = GetGamePool('CObject')
    local closest_object, closest_coords
    max_distance = max_distance or 2.0
    for i = 1, #objects do
        local object = objects[i]
        local object_coords = GetEntityCoords(object)
        local distance = #(coords - object_coords)
        if distance < max_distance then
            max_distance = distance
            closest_object = object
            closest_coords = object_coords
        end
    end
    return closest_object, closest_coords
end

exports('entities_get_closest_object', get_closest_object)
utils.entities.get_closest_object = get_closest_object

Example

--- Returns closest object to coords within 10.0
local closest_obj, closest_coords = utils.entities.get_closest_object({x = 0, y = 0, z = 0}, 10.0)

get_closest_ped()

Gets closest ped to specified coords within radius.

Function

local function get_closest_ped(coords, max_distance)
    local peds = GetGamePool('CPed')
    local closest_ped, closest_coords
    max_distance = max_distance or 2.0
    for i = 1, #peds do
        local ped = peds[i]
        if not IsPedAPlayer(ped) then
            local ped_coords = GetEntityCoords(ped)
            local distance = #(coords - ped_coords)
            if distance < max_distance then
                max_distance = distance
                closest_ped = ped
                closest_coords = ped_coords
            end
        end
    end
    return closest_ped, closest_coords
end

exports('entities_get_closest_ped', get_closest_ped)
utils.entities.get_closest_ped = get_closest_ped

Example

--- Returns closest ped to coords within 10.0
local closest_ped, closest_coords = utils.entities.get_closest_ped({x = 0, y = 0, z = 0}, 10.0)

get_closest_player()

Gets closest player to specified coords within radius.

Function

local function get_closest_player(coords, max_distance, include_player)
    local players = GetActivePlayers()
    local closest_id, closest_ped, closest_coords
    max_distance = max_distance or 2.0
    for i = 1, #players do
        local player_id = players[i]
        if player_id ~= PlayerId() or include_player then
            local player_ped = GetPlayerPed(player_id)
            local player_coords = GetEntityCoords(player_ped)
            local distance = #(coords - player_coords)
            if distance < max_distance then
                max_distance = distance
                closest_id = player_id
                closest_ped = player_ped
                closest_coords = player_coords
            end
        end
    end
    return closest_id, closest_ped, closest_coords
end

exports('entities_get_closest_player', get_closest_player)
utils.entities.get_closest_player = get_closest_player

Example

--- Returns closest player to coords within 10.0 and ignore the player
local closest_id, closest_ped, closest_coords = utils.entities.get_closest_player({x = 0, y = 0, z = 0}, 10.0, false)

--- Returns closest player to coords within 10.0 and include the player
local closest_id, closest_ped, closest_coords = utils.entities.get_closest_player({x = 0, y = 0, z = 0}, 10.0, true)

get_closest_vehicle()

Gets closest vehicle to specified coords within radius.

Function

local function get_closest_vehicle(coords, max_distance, player_vehicle)
    local vehicles = GetGamePool('CVehicle')
    local closest_vehicle, closest_coords
    max_distance = max_distance or 2.0
    for i = 1, #vehicles do
        local vehicle = vehicles[i]
        if not IsPedInVehicle(PlayerPedId(), vehicle, true) or player_vehicle then
            local vehicle_coords = GetEntityCoords(vehicle)
            local distance = #(coords - vehicle_coords)
            if distance < max_distance then
                max_distance = distance
                closest_vehicle = vehicle
                closest_coords = vehicle_coords
            end
        end
    end
    return closest_vehicle, closest_coords
end

exports('entities_get_closest_vehicle', get_closest_vehicle)
utils.entities.get_closest_vehicle = get_closest_vehicle

Example

--- Returns closest vehicle to coords within 10.0 and ignore the players vehicle
local closest_vehicle, closest_coords = utils.entities.get_closest_vehicle({x = 0, y = 0, z = 0}, 10.0, false)

--- Returns closest vehicle to coords within 10.0 and include the players vehicle
local closest_vehicle, closest_coords = utils.entities.get_closest_vehicle({x = 0, y = 0, z = 0}, 10.0, true)

get_entities_in_front_of_player()

Gets all entities infront of player within specified field of view and distance.

Function

local function get_entities_in_front_of_player(fov, distance)
    local player = PlayerPedId()
    local player_coords = GetEntityCoords(player)
    local forward_vector = GetEntityForwardVector(player)
    local end_coords = vector3(player_coords.x + forward_vector.x * distance, player_coords.y + forward_vector.y * distance, player_coords.z + forward_vector.z * distance)
    local hit, _, _, _, entity = StartShapeTestRay(player_coords.x, player_coords.y, player_coords.z, end_coords.x, end_coords.y, end_coords.z, -1, player, 0)
    if hit then
        local entity_type = GetEntityType(entity)
        if entity_type ~= 0 then 
            return entity
        end
    end
    return nil
end

exports('entities_get_entities_in_front_of_player', get_entities_in_front_of_player)
utils.entities.get_entities_in_front_of_player = get_entities_in_front_of_player

Example

--- Returns entities in front of player.
local entities_in_front = utils.entities.get_entities_in_front_of_player(45.0, 10.0)

get_target_ped()

Gets the ped a player is looking at or nearest to the player.

Function

local function get_target_ped(player_ped, fov, distance)
    local entity = get_entities_in_front_of_player(fov, distance)
    if entity and IsEntityAPed(entity) and not IsPedAPlayer(entity) then
        return entity, GetEntityCoords(entity)
    end
    local player_coords = GetEntityCoords(player_ped)
    local target_ped, target_coords = get_closest_ped(player_coords, 5.0)
    return target_ped, target_coords
end

exports('entities_get_target_ped', get_target_ped)
utils.entities.get_target_ped = get_target_ped

Example

--- Returns the ped player is looking at or nearest
local target_ped = utils.entities.get_target_ped(PlayerPedId(), 45.0, 10.0)