Vehicles

CLIENT SIDE ONLY

A large selection of vehicle related functions to cover pretty much anything that should be needed.

Functions

get_vehicle_plate

Retrieves the license plate number of the specified vehicle.

Function

local function get_vehicle_plate(vehicle)
    if vehicle == 0 then return end
    return utils.strings.trim(GetVehicleNumberPlateText(vehicle))
end

exports('get_vehicle_plate', get_vehicle_plate)
utils.vehicles.get_vehicle_plate = get_vehicle_plate

Example

--- Retreive Vehicle
local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)

--- Utils object
local plate = utils.vehicles.get_vehicle_plate(vehicle)

print("Vehicle Plate:", plate)

--- Direct export
local plate = exports.boii_utils:get_vehicle_plate(vehicle)

get_vehicle_model

Retrieves the model name of the specified vehicle.

Function

local function get_vehicle_model(vehicle)
    local hash = GetEntityModel(vehicle)
    local name = GetDisplayNameFromVehicleModel(hash)
    return string.lower(name)
end

exports('get_vehicle_model', get_vehicle_model)
utils.vehicles.get_vehicle_model = get_vehicle_model

Example

--- Retreive Vehicle
local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)

--- Utils object
local model = utils.vehicles.get_vehicle_model(vehicle)

print("Vehicle Model:", model)

--- Direct export
local model = exports.boii_utils:get_vehicle_model(vehicle)

get_doors_broken

Returns a list of broken doors for the specified vehicle

Function

local function get_doors_broken(vehicle)
    local doors_broken = {}
    local num_doors = GetNumberOfVehicleDoors(vehicle)
    if num_doors and num_doors > 0 then
        for door_id = 0, num_doors - 1 do
            doors_broken[tostring(door_id)] = IsVehicleDoorDamaged(vehicle, door_id)
        end
    end
    return doors_broken
end

exports('get_doors_broken', get_doors_broken)
utils.vehicles.get_doors_broken = get_doors_broken

Example

--- Retreive Vehicle
local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)

--- Utils object
local doors_broken = utils.vehicles.get_doors_broken(vehicle)

print("Broken Doors:", json.encode(doors_broken))

--- Direct export
local doors_broken = exports.boii_utils:get_doors_broken(vehicle)

get_window_broken

Returns a list of broken windows for the specified vehicle.

Function

local function get_windows_broken(vehicle)
    local windows_broken = {}
    for window_id = 0, 13 do
        windows_broken[tostring(window_id)] = not IsVehicleWindowIntact(vehicle, window_id)
    end
    return windows_broken
end

exports('get_windows_broken', get_windows_broken)
utils.vehicles.get_windows_broken = get_windows_broken

Example

--- Retreive vehicle
local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)

--- Utils object
local windows_broken = utils.vehicles.get_windows_broken(vehicle)

print("Broken Windows (Utils):", json.encode(windows_broken))

--- Direct export
local windows_broken = exports.boii_utils:get_windows_broken(vehicle)

get_tyre_burst

Returns a list of burst tyres for the specified vehicle.

Function

local function get_tyre_burst(vehicle)
    local tyre_burst = {}
    local tyres_index = {
        ['2'] = {0, 4},
        ['3'] = {0, 1, 4, 5},
        ['4'] = {0, 1, 4, 5},
        ['6'] = {0, 1, 2, 3, 4, 5}
    }
    local num_wheels = tostring(GetVehicleNumberOfWheels(vehicle))
    if tyres_index[num_wheels] then
        for _, idx in pairs(tyres_index[num_wheels]) do
            tyre_burst[tostring(idx)] = IsVehicleTyreBurst(vehicle, idx, false)
        end
    end
    return tyre_burst
end

exports('get_tyre_burst', get_tyre_burst)
utils.vehicles.get_tyre_burst = get_tyre_burst

Example

--- Retreive vehicle
local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)

--- Utils object
local burst_tyres = utils.vehicles.get_tyre_burst(vehicle)

print("Burst Tyres:", json.encode(burst_tyres))

--- Direct export
local burst_tyres = exports.boii_utils:get_tyre_burst(vehicle)

get_vehicle_extras

Retrieves the enabled extras for the specified vehicle.

Function

local function get_vehicle_extras(vehicle)
    local extras = {}
    for extra_id = 0, 20 do
        if DoesExtraExist(vehicle, extra_id) then
            extras[tostring(extra_id)] = IsVehicleExtraTurnedOn(vehicle, extra_id)
        end
    end
    return extras
end

exports('get_vehicle_extras', get_vehicle_extras)
utils.vehicles.get_vehicle_extras = get_vehicle_extras

Example

--- Retreive vehicle
local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)

--- Utils object
local extras = utils.vehicles.get_vehicle_extras(vehicle)

print("Vehicle Extras:", json.encode(extras))

--- Direct export
local extras = exports.boii_utils:get_vehicle_extras(vehicle)

get_custom_xenon_colour

Retrieves the custom xenon color of the specified vehicle.

Function

local function get_custom_xenon_color(vehicle)
    local has_custom_xenon_color, r, g, b = GetVehicleXenonLightsCustomColor(vehicle)
    if has_custom_xenon_color then
        return {r, g, b}
    else
        return nil
    end
end

exports('get_custom_xenon_color', get_custom_xenon_color)
utils.vehicles.get_custom_xenon_color = get_custom_xenon_color

Example

--- Retreive Vehicle
local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)

--- Utils object
local xenon_color = utils.vehicles.get_custom_xenon_color(vehicle)

print("Custom Xenon Color:", xenon_color and json.encode(xenon_color) or "None")

--- Direct export
local xenon_color = exports.boii_utils:get_custom_xenon_color(vehicle)

get_vehicle_mod

Retrieves the modification of a specific type for the specified vehicle.

Function

local function get_vehicle_mod(vehicle, mod_type)
    return {
        index = GetVehicleMod(vehicle, mod_type),
        variation = GetVehicleModVariation(vehicle, mod_type)
    }
end

exports('get_vehicle_mod', get_vehicle_mod)
utils.vehicles.get_vehicle_mod = get_vehicle_mod

Example

--- Retreive Vehicle
local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)
--- Define mod type
local mod_type = 15

--- Utils object
local mod = utils.vehicles.get_vehicle_mod(vehicle, mod_type)

print("Vehicle Mod:", json.encode(mod))

--- Direct export
local mod = exports.boii_utils:get_vehicle_mod(vehicle, mod_type)

get_vehicle_properties

Retrieves various detailed properties of the specified vehicle.

Function

local function get_vehicle_properties(vehicle)
    if not DoesEntityExist(vehicle) then
        return
    end
    local color_primary, color_secondary = GetVehicleColours(vehicle)
    local pearlescent_color, wheel_color = GetVehicleExtraColours(vehicle)
    local has_custom_primary_color = GetIsVehiclePrimaryColourCustom(vehicle)
    local custom_primary_color = has_custom_primary_color and { GetVehicleCustomPrimaryColour(vehicle) } or nil
    local has_custom_secondary_color = GetIsVehicleSecondaryColourCustom(vehicle)
    local custom_secondary_color = has_custom_secondary_color and { GetVehicleCustomSecondaryColour(vehicle) } or nil
    local mods = {}
    for mod_type = 0, 49 do
        mods[mod_type] = get_vehicle_mod(vehicle, mod_type)
    end
    return {
        model = GetEntityModel(vehicle),
        doors_broken = get_doors_broken(vehicle),
        windows_broken = get_windows_broken(vehicle),
        tyre_burst = get_tyre_burst(vehicle),
        tyres_can_burst = GetVehicleTyresCanBurst(vehicle),
        plate = boii.trim_string(GetVehicleNumberPlateText(vehicle)),
        plate_index = GetVehicleNumberPlateTextIndex(vehicle),
        body_health = utils.maths.round_number(GetVehicleBodyHealth(vehicle), 1),
        engine_health = utils.maths.round_number(GetVehicleEngineHealth(vehicle), 1),
        tank_health = utils.maths.round_number(GetVehiclePetrolTankHealth(vehicle), 1),
        fuel_level = utils.maths.round_number(GetVehicleFuelLevel(vehicle), 1),
        dirt_level = utils.maths.round_number(GetVehicleDirtLevel(vehicle), 1),
        color1 = color_primary,
        color2 = color_secondary,
        custom_primary_color = custom_primary_color,
        custom_secondary_color = custom_secondary_color,
        pearlescent_color = pearlescent_color,
        wheel_color = wheel_color,
        dashboard_color = GetVehicleDashboardColour(vehicle),
        interior_color = GetVehicleInteriorColour(vehicle),
        wheels = GetVehicleWheelType(vehicle),
        window_tint = GetVehicleWindowTint(vehicle),
        xenon_color = GetVehicleXenonLightsColor(vehicle),
        custom_xenon_color = get_custom_xenon_color(vehicle),
        neon_enabled = get_neon_enabled(vehicle),
        neon_color = table.pack(GetVehicleNeonLightsColour(vehicle)),
        extras = get_vehicle_extras(vehicle),
        tyre_smoke_color = table.pack(GetVehicleTyreSmokeColor(vehicle)),
        mods = mods
    }
end

exports('get_vehicle_properties', get_vehicle_properties)
utils.vehicles.get_vehicle_properties = get_vehicle_properties

Example

--- Retreive vehicle
local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)

--- Utils object
local properties = utils.vehicles.get_vehicle_properties(vehicle)

print("Vehicle Properties:", json.encode(properties))

--- Direct export
local properties = exports.boii_utils:get_vehicle_properties(vehicle)

get_vehicle_mods_and_maintenance

Retrieves the mods and maintenance data for the specified vehicle.

Function

local function get_vehicle_mods_and_maintenance(vehicle)
    if DoesEntityExist(vehicle) then
        local pearlescent_color, wheel_color = GetVehicleExtraColours(vehicle)
        local r, g, b = GetVehicleCustomPrimaryColour(vehicle)
        if not (r and g and b) then
            r, g, b = 0, 0, 0
        end
        local colour_primary = {r = r, g = g, b = b}
        local r2, g2, b2 = GetVehicleCustomSecondaryColour(vehicle)
        if not (r2 and g2 and b2) then
            r2, g2, b2 = 0, 0, 0
        end
        local colour_secondary = {r = r2, g = g2, b = b2}
        local mod_livery = GetVehicleMod(vehicle, 48)
        if GetVehicleMod(vehicle, 48) == -1 and GetVehicleLivery(vehicle) ~= 0 then
            mod_livery = GetVehicleLivery(vehicle)
        end
        local extras = {}
        for extra_id = 0, 12 do
            if DoesExtraExist(vehicle, extra_id) then
                local state = IsVehicleExtraTurnedOn(vehicle, extra_id) == 1
                extras[tostring(extra_id)] = state
            end
        end
        local num_wheels = GetVehicleNumberOfWheels(vehicle)
        local tyre_health = {}
        for i = 0, num_wheels - 1 do
            tyre_health[i] = GetVehicleWheelHealth(vehicle, i)
        end
        local window_status = {}
        for i = 0, 7 do
            window_status[i] = IsVehicleWindowIntact(vehicle, i) == 1
        end
        local door_status = {}
        local num_doors = GetNumberOfVehicleDoors(vehicle)
        for i = 0, num_doors - 1 do
            door_status[i] = IsVehicleDoorDamaged(vehicle, i) == 1
        end
        local modifications = {
            model = GetEntityModel(vehicle),
            plate_index = GetVehicleNumberPlateTextIndex(vehicle),
            colour_primary = colour_primary,
            colour_secondary = colour_secondary,
            pearlescent_color = pearlescent_color,
            wheel_color = wheel_color,
            wheels = GetVehicleWheelType(vehicle),
            window_tint = GetVehicleWindowTint(vehicle),
            xenons = IsToggleModOn(vehicle, 22),
            xenon_color = GetVehicleXenonLightsColour(vehicle),
            neon_enabled = {
                IsVehicleNeonLightEnabled(vehicle, 0),
                IsVehicleNeonLightEnabled(vehicle, 1),
                IsVehicleNeonLightEnabled(vehicle, 2),
                IsVehicleNeonLightEnabled(vehicle, 3)
            },
            neon_color = table.pack(GetVehicleNeonLightsColour(vehicle)),
            headlight_color = GetVehicleHeadlightsColour(vehicle),
            tire_smoke_color = table.pack(GetVehicleTyreSmokeColor(vehicle)),
            livery = mod_livery,
            extras = extras
        }
        local maintenance = {
            mileage = 0,
            fuel = GetVehicleFuelLevel(vehicle),
            oil = GetVehicleOilLevel(vehicle),
            engine = GetVehicleEngineHealth(vehicle),
            body = GetVehicleBodyHealth(vehicle),
            gearbox = 1000,
            clutch = GetVehicleClutch(vehicle),
            suspension = 1000,
            petrol_tank = GetVehiclePetrolTankHealth(vehicle),
            dirt = GetVehicleDirtLevel(vehicle),
            door_status = {},
            window_status = {},
            tyres = {
                burst_state = {},
                burst_completely = {},
            }
        }
        for i = 0, num_wheels - 1 do
            maintenance.tyres.burst_state[i] = not not IsVehicleTyreBurst(vehicle, i, false)
            maintenance.tyres.burst_completely[i] = not not IsVehicleTyreBurst(vehicle, i, true)
        end
        maintenance.tyre_health = tyre_health
        maintenance.window_status = window_status
        maintenance.door_status = door_status
        return modifications, maintenance
    else
        return nil, nil
    end
end

exports('get_vehicle_mods_and_maintenance', get_vehicle_mods_and_maintenance)
utils.vehicles.get_vehicle_mods_and_maintenance = get_vehicle_mods_and_maintenance

Example

--- Retreive vehicle
local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)

--- Utils object
local mods, maintenance = utils.vehicles.get_vehicle_mods_and_maintenance(vehicle)

print("Vehicle Mods:", json.encode(mods))
print("Vehicle Maintenance:", json.encode(maintenance))

--- Direct export
local mods, maintenance = exports.boii_utils:get_vehicle_mods_and_maintenance(vehicle)

get_vehicle_class

Retrieves the class of the specified vehicle as a string.

Function

local function get_vehicle_class(vehicle)
    local classes = {
        [0] = 'compacts',
        [1] = 'sedans',
        [2] = 'suvs',
        [3] = 'coupes',
        [4] = 'muscle',
        [5] = 'sports classics',
        [6] = 'sports',
        [7] = 'super',
        [8] = 'motorcycles',
        [9] = 'off-road',
        [10] = 'industrial',
        [11] = 'utility',
        [12] = 'vans',
        [13] = 'cycles',
        [14] = 'boats',
        [15] = 'helicopters',
        [16] = 'planes',
        [17] = 'service',
        [18] = 'emergency',
        [19] = 'military',
        [20] = 'commercial',
        [21] = 'trains',
    }
    local class_id = GetVehicleClass(vehicle)
    return classes[class_id] or 'Unknown'
end

exports('get_vehicle_class', get_vehicle_class)
utils.vehicles.get_vehicle_class = get_vehicle_class

Example

--- Retreive vehicle
local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)

--- Utils object
local class = utils.vehicles.get_vehicle_class(vehicle)
print("Vehicle Class:", class)

--- Direct export
local class = exports.boii_utils:get_vehicle_class(vehicle)

get_vehicle_class_details

Retrieves detailed class information of the specified vehicle.

Function

local function get_vehicle_class_details(vehicle)
    if not vehicle then return nil end
    local class_id = GetVehicleClass(vehicle)
    local class_details = {
        class_id = class_id,
        class_name = get_vehicle_class(vehicle), -- using the function we defined earlier
        estimated_max_speed = GetVehicleClassEstimatedMaxSpeed(class_id),
        max_acceleration = GetVehicleClassMaxAcceleration(class_id),
        max_agility = GetVehicleClassMaxAgility(class_id),
        max_braking = GetVehicleClassMaxBraking(class_id),
        max_traction = GetVehicleClassMaxTraction(class_id)
    }
    return class_details
end

exports('get_vehicle_class_details', get_vehicle_class_details)
utils.vehicles.get_vehicle_class_details = get_vehicle_class_details

Example

--- Retreive vehicle
local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)

--- Utils object
local class_details = utils.vehicles.get_vehicle_class_details(vehicle)
print("Vehicle Class Details:", json.encode(class_details))

--- Direct export
local class_details = exports.boii_utils:get_vehicle_class_details(vehicle)

get_vehicle_details

Retrieves detailed information about a vehicle, optionally the one the player is currently in.

Function

local function get_vehicle_details(use_current_vehicle)
    local player = PlayerPedId()
    local player_coords = GetEntityCoords(player)
    local vehicle_data = {}
    local vehicle
    if use_current_vehicle and IsPedInAnyVehicle(player, false) then
        vehicle = GetVehiclePedIsIn(player, false)
    else
        vehicle, vehicle_data.distance = utils.entities.get_closest_vehicle(player_coords, 10.0, false)
        vehicle_data.distance = #(player_coords - GetEntityCoords(vehicle))
    end
    if not vehicle then
        return nil
    end
    vehicle_data.vehicle = vehicle
    vehicle_data.plate = get_vehicle_plate(vehicle)
    vehicle_data.model = get_vehicle_model(vehicle)
    vehicle_data.class = get_vehicle_class(vehicle)
    vehicle_data.mods, vehicle_data.maintenance = get_vehicle_mods_and_maintenance(vehicle)
    local rear_engine_vehicles = { 'comet', 'infernusclassic', '811', 're7b', '9f', '9fcabrio', 'osiris', 'tyrus', 'adder', 'stinger', 'reaper', 'spacedocker', 'cometsafari', 'krieger', 'f19', 'injection', 'tropos' }
    vehicle_data.is_rear_engine = false
    for _, model in ipairs(rear_engine_vehicles) do
        if string.lower(vehicle_data.model) == model then
            vehicle_data.is_rear_engine = true
            break
        end
    end
    return vehicle_data
end

exports('get_vehicle_details', get_vehicle_details)
utils.vehicles.get_vehicle_details = get_vehicle_details

Example

--- Toggle if players vehicle should be used.
--- If false the closest vehicle will be used.
local use_players_vehicle = true

--- Utils object
local vehicle_details = utils.vehicles.get_vehicle_details(use_players_vehicle)

print("Vehicle Details:", json.encode(vehicle_details))

--- Direct export
local vehicle_details = exports.boii_utils:get_vehicle_details(use_players_vehicle)

spawn_vehicle

Spawns a vehicle with specified properties and modifications.

Function

local function spawn_vehicle(vehicle_data)
    local model = vehicle_data.model
    local coords = vehicle_data.coords
    local is_network = vehicle_data.is_network
    local net_mission_entity = vehicle_data.net_mission_entity
    local hash = GetHashKey(model)
    utils.requests.model(hash)
    local vehicle = CreateVehicle(hash, coords.x, coords.y, coords.z, coords.w, is_network, net_mission_entity)
    if vehicle_data.custom_plate then
        SetVehicleNumberPlateText(vehicle, vehicle_data.custom_plate)
    end
    if vehicle_data.damages then
        if damages.doors then
            for _, doorId in ipairs(damages.doors.ids) do
                SetVehicleDoorBroken(vehicle, doorId, true)
            end
        end
        if damages.windows then
            for i = 0, 7 do
                SmashVehicleWindow(vehicle, i)
            end
        end
        if damages.tyres then
            for _, tyreId in ipairs(damages.tyres.ids) do
                SetVehicleTyreBurst(vehicle, tyreId, damages.tyres.burst_completely, 1000)
            end
        end
    end
    if vehicle_data.maintenance then
        local m = vehicle_data.maintenance
        SetVehicleFuelLevel(vehicle, m.fuel or 100.0)
        SetVehicleOilLevel(vehicle, m.oil or 1000.0)
        SetVehicleEngineHealth(vehicle, m.engine or 1000.0)
        SetVehicleBodyHealth(vehicle, m.body or 1000.0)
        SetVehiclePetrolTankHealth(vehicle, m.petrol_tank or 1000.0)
        SetVehicleDirtLevel(vehicle, m.dirt or 0.0)
    end
    if vehicle_data.mods then
        if vehicle_data.mods.random then
            for mod_type = 0, 49 do
                local max = GetNumVehicleMods(vehicle, mod_type)
                SetVehicleMod(vehicle, mod_type, math.random(0, max - 1), false)
            end
        end
        if vehicle_data.mods.max_performance then
            for mod_type = 0, 49 do
                local max = GetNumVehicleMods(vehicle, mod_type)
                SetVehicleMod(vehicle, mod_type, max - 1, false)
            end
        end
        if vehicle_data.mods.ids then
            for mod_type, modIndex in pairs(mods.ids) do
                SetVehicleMod(vehicle, mod_type, modIndex, false)
            end
        end
        if vehicle_data.mods.custom_paint then
            local cp = vehicle_data.mods.custom_paint
            if cp.primary then
                SetVehicleCustomPrimaryColour(vehicle, cp.primary.r, cp.primary.g, cp.primary.b)
            end
            if cp.secondary then
                SetVehicleCustomSecondaryColour(vehicle, cp.secondary.r, cp.secondary.g, cp.secondary.b)
            end
        end
        if vehicle_data.mods.neon_lights then
            for i = 0, 3 do
                SetVehicleNeonLightEnabled(vehicle, i, true)
            end
            SetVehicleNeonLightsColour(vehicle, vehicle_data.mods.neon_lights.colour.r, vehicle_data.mods.neon_lights.colour.g, vehicle_data.mods.neon_lights.colour.b)
        end
        if vehicle_data.mods.xenon_lights then
            ToggleVehicleMod(vehicle, 22, true)
            if vehicle_data.mods.xenon_lights.colour then
                SetVehicleHeadlightsColour(vehicle, vehicle_data.mods.xenon_lights.colour)
            end
        end
        if vehicle_data.mods.bulletproof_tyres then
            SetVehicleTyresCanBurst(vehicle, false)
        end
        if vehicle_data.mods.engine_audio then
            ForceVehicleEngineAudio(vehicle, vehicle_data.mods.engine_audio)
        end
        if vehicle_data.mods.livery then
            SetVehicleLivery(vehicle, vehicle_data.mods.livery)
        end
        if vehicle_data.mods.plate_style then
            SetVehicleNumberPlateTextIndex(vehicle, vehicle_data.mods.plate_style)
        end
        if vehicle_data.mods.window_tint then
            SetVehicleWindowTint(vehicle, vehicle_data.mods.window_tint)
        end
        if vehicle_data.mods.top_speed then
            SetVehicleEnginePowerMultiplier(vehicle, vehicle_data.mods.top_speed)
        end
        if vehicle_data.mods.handling_tweaks then
            for property, value in pairs(vehicle_data.mods.handling_tweaks) do
                SetVehicleHandlingFloat(vehicle, 'CHandlingData', property, value)
            end
        end
    end
    if vehicle_data.lock_doors then
        SetVehicleDoorsLocked(vehicle, 2)
    end
    if vehicle_data.invincible then
        SetEntityInvincible(vehicle, true)
    end
    PlaceObjectOnGroundProperly(vehicle)
    if vehicle_data.set_into_vehicle then
        local playerPed = PlayerPedId()
        SetPedIntoVehicle(playerPed, vehicle, -1)
    end
    return vehicle
end

exports('spawn_vehicle', spawn_vehicle)
utils.vehicles.spawn_vehicle = spawn_vehicle

Example

--- Define vehicle data
local vehicle_data = {
    model = "adder",
    coords = vector4(0.0, 0.0, 75.0, 0.0),
    is_network = false,
    net_mission_entity = true,
    custom_plate = "SPAWNED",
    lock_doors = true,
    invincible = true,
    maintenance = {
        fuel = 80.0,
        engine = 900.0,
    },
    mods = {
        max_performance = true,
        custom_paint = {
            primary = { r = 255, g = 0, b = 0 },
            secondary = { r = 0, g = 0, b = 255 },
        },
    },
}

--- Utils object
local vehicle = utils.vehicles.spawn_vehicle(vehicle_data)

print("Spawned Vehicle:", vehicle)

--- Direct export
local vehicle = exports.boii_utils:spawn_vehicle(vehicle_data)