Blips

The utils.blips module in our utility library is designed to enhance the interaction with map markers or "blips" within the game environment.

Functions

create_blip()

Creates a single blip and stores in created blips.

Function

local function create_blip(blip_data)
    if blip_data.show then
        local blip = AddBlipForCoord(blip_data.coords.x, blip_data.coords.y, blip_data.coords.z)
        SetBlipSprite(blip, blip_data.sprite)
        SetBlipColour(blip, blip_data.colour)
        SetBlipScale(blip, blip_data.scale)
        SetBlipAsShortRange(blip, true)
        BeginTextCommandSetBlipName('STRING')
        AddTextComponentString(blip_data.label)
        EndTextCommandSetBlipName(blip)
        created_blips[#created_blips + 1] = { blip = blip, category = blip_data.category, label = blip_data.label, coords = blip_data.coords, sprite = blip_data.sprite, colour = blip_data.colour, scale = blip_data.scale }
        category_state[blip_data.category] = true
    end
end

exports('blips_create_blip', create_blip)
utils.blips.create_blip = create_blip

Example

utils.blips.create_blip({ 
    coords = vector3(100.0, 200.0, 30.0), 
    sprite = 1, 
    colour = 1, 
    scale = 1.5, 
    label = 'Blip 1', 
    category = 'shop', 
    show = true 
})

create_blips()

Creates multiple blips from tabled data.

Function

local function create_blips(blip_config)
    for _, blip_data in pairs(blip_config) do
        create_blip(blip_data)
    end
end

exports('blips_create_blips', create_blips)
utils.blips.create_blips = create_blips

Example

--- Create a table of blips to be created.
local blips = {
    { coords = vector3(100.0, 200.0, 30.0), sprite = 1, colour = 1, scale = 1.5, label = 'Blip 1', category = 'shop', show = true }
}
utils.blips.create_blips(blips)

toggle_all_blips()

Toggles visibility of all blips within the created blips table.

Function

local function toggle_all_blips(visible)
    local id = visible and 2 or 0
    for _, blip_data in ipairs(created_blips) do
        SetBlipDisplay(blip_data.blip, id)
    end
    BLIPS_ENABLED = visible
end

exports('blips_toggle_all_blips', toggle_all_blips)
utils.blips.toggle_all_blips = toggle_all_blips

Example

--- Show blips.
utils.blips.toggle_all_blips(true)

--- Hide blips.
utils.blips.toggle_all_blips(false)

toggle_blips_by_category()

Toggle visibility of a specified blip category.

Function

local function toggle_blips_by_category(category, state)
    for _, blip_data in ipairs(created_blips) do
        if blip_data.category == category then
            SetBlipDisplay(blip_data.blip, state and 3 or 0)
        end
    end
    category_state[category] = state
end

exports('blips_toggle_blips_by_category', toggle_blips_by_category)
utils.blips.toggle_blips_by_category = toggle_blips_by_category

Example

--- Show all blips in the 'shop' category.
utils.blips.toggle_blips_by_category('shop', true)

--- Hide all blips in the 'shop' category.
utils.blips.toggle_blips_by_category('shop', false)

remove_blip()

Removes a specific blip from the game world and created blips table.

Function

local function remove_blip(blip)
    if DoesBlipExist(blip) then
        RemoveBlip(blip)
    end
    if created_blips[blip] then
        created_blips[blip] = nil
    end
end

exports('blips_remove_blip', remove_blip)
utils.blips.remove_blip = remove_blip

Example

--- Remove blip 1.
utils.blips.remove_blip(1)

remove_all_blips()

Removes all blips from game world and created blips table.

Function

local function remove_all_blips()
    for blip_id in pairs(created_blips) do
        remove_blip(blip_id)
    end
    created_blips = {}
end
exports('blips_remove_all_blips', remove_all_blips)
utils.blips.remove_all_blips = remove_all_blips

Example

utils.blips.remove_all_blips()

remove_blips_by_categories()

Removes all blips in specified categories.

Function

local function remove_blips_by_categories(categories)
    for blip_id, blip_data in pairs(created_blips) do
        for _, category in ipairs(categories) do
            if blip_data.category == category then
                remove_blip(blip_id)
                break
            end
        end
    end
end

exports('blips_remove_blips_by_categories', remove_blips_by_categories)
utils.blips.remove_blips_by_categories = remove_blips_by_categories

Example

--- Removes all blips in the 'shop' and 'house' categories.
utils.blips.remove_blips_by_categories({'shop', 'house'})

create_blip_alpha()

Creates a blip with customisable alpha, duration and optional colour palette.

Function

local function create_blip_alpha(options)
    local blip = AddBlipForCoord(options.coords)
    SetBlipSprite(blip, options.sprite)
    SetBlipColour(blip, options.colour)
    SetBlipScale(blip, options.scale)
    SetBlipAsShortRange(blip, true)
    BeginTextCommandSetBlipName("STRING")
    AddTextComponentString(options.label)
    EndTextCommandSetBlipName(blip)
    local alpha = options.alpha
    local duration = options.duration * 1000
    local start_time = GetGameTimer()
    local step_time = 100
    local steps = duration / step_time
    local alpha_decrement = alpha / steps
    local colour_palette = options.colour_palette or {options.colour}
    local current_color_index = 1
    CreateThread(function()
        while alpha > 0 do
            alpha = alpha - alpha_decrement
            if alpha <= 0 then
                RemoveBlip(blip)
                return
            end
            SetBlipAlpha(blip, math.floor(alpha))
            Wait(step_time)
        end
    end)
    CreateThread(function()
        while alpha > 0 do
            if #colour_palette > 1 then
                current_color_index = current_color_index % #colour_palette + 1
                SetBlipColour(blip, colour_palette[current_color_index])
            end
            Wait(750)
        end
    end)
end

exports('blips_create_blip_alpha', create_blip_alpha)
utils.blips.create_blip_alpha = create_blip_alpha

Example

--- Create a blip with alpha, duration and multi colours.
utils.blips.create_blip_alpha({
    coords = vector3(100.0, 200.0, 30.0),
    sprite = 161,
    colour = 1, 
    scale = 1.5, 
    label = 'Example Blip',
    alpha = 250,
    duration = 10,
    colour_palette = {1, 3}
})

update_blip_label()

Updates the label of the specified blip.

Function

local function update_blip_label(blip, new_label)
    if DoesBlipExist(blip) then
        BeginTextCommandSetBlipName("STRING")
        AddTextComponentString(new_label)
        EndTextCommandSetBlipName(blip)
        if created_blips[blip] then
            created_blips[blip].label = new_label
        end
    end
end

exports('blips_update_blip_label', update_blip_label)
utils.blips.update_blip_label = update_blip_label

Example

--- Change the label for blip 1.
utils.blips.update_blip_label(1, 'New Label')

update_blip_sprite()

Updates the sprite of a specifed blip.

Function

local function update_blip_sprite(blip, new_sprite)
    if DoesBlipExist(blip) then
        SetBlipSprite(blip, new_sprite)
        if created_blips[blip] then
            created_blips[blip].sprite = new_sprite
        end
    end
end

exports('blips_update_blip_sprite', update_blip_sprite)
utils.blips.update_blip_sprite = update_blip_sprite

Example

--- Change the sprite for blip 1.
utils.blips.update_blip_sprite(1, 162)

update_blip_colour()

Updates the colour of a specified blip.

Function

local function update_blip_colour(blip, new_colour)
    if DoesBlipExist(blip) then
        SetBlipColour(blip, new_colour)
        if created_blips[blip] then
            created_blips[blip].colour = new_colour
        end
    end
end

exports('blips_update_blip_colour', update_blip_colour)
utils.blips.update_blip_colour = update_blip_colour

Example

--- Change the colour of blip 1.
utils.blips.update_blip_colour(1, 2)

update_blip_scale()

Updates the scale of a specified blip.

Function

local function update_blip_scale(blip, new_scale)
    if DoesBlipExist(blip) then
        SetBlipScale(blip, new_scale)
        if created_blips[blip] then
            created_blips[blip].scale = new_scale
        end
    end
end

exports('blips_update_blip_scale', update_blip_scale)
utils.blips.update_blip_scale = update_blip_scale

Example

--- Change scale of blip 1.
utils.blips.update_blip_scale(1, 2.0)

are_blips_enabled()

Check if player has blips enabled or not.

Function

local function are_blips_enabled()
    return BLIPS_ENABLED
end

exports('blips_are_blips_enabled', are_blips_enabled)
utils.blips.are_blips_enabled = are_blips_enabled

Example

--- Return if player has blips enabled.
local enabled = utils.blips.are_blips_enabled()

get_category_state()

Gets the visiblity state of a specified category.

Function

local function get_category_state(category)
    return category_state[category] or false
end

exports('blips_get_category_state', get_category_state)
utils.blips.get_category_state = get_category_state

Example

--- Return visiblity state for blips in 'shop' category.
local state = utils.blips.get_category_state('shop')

get_all_blips()

Returns the full created blips table.

Function

local function get_all_blips()
    return created_blips
end

exports('blips_get_all_blips', get_all_blips)
utils.blips.get_all_blips = get_all_blips

Example

--- Return all blips.
local all_blips = utils.blips.get_all_blips()

get_blips_by_category()

Gets all blips in a specified category.

Function

local function get_blips_by_category(category)
    local blips = {}
    for blip_id, blip_data in pairs(created_blips) do
        if blip_data.category == category then
            blips[#blips+1] = blip_id
        end
    end
    return blips
end

exports('blips_get_blips_by_category', get_blips_by_category)
utils.blips.get_blips_by_category = get_blips_by_category

Example

--- Return all blips in 'shop' category.
local shop_blips = utils.blips.get_blips_by_category('shop')

get_blip_label()

Gets the label of a specified blip.

Function

local function get_blip_label(blip)
    if created_blips[blip] then
        return created_blips[blip].label
    end
    return ''
end

exports('blips_get_blip_label', get_blip_label)
utils.blips.get_blip_label = get_blip_label

Example

--- Return the label of blip 1.
local label = utils.blips.get_blip_label(1)

pulse_blip()

Pulses a specified blip.

Function

local function pulse_blip(blip)
    if DoesBlipExist(blip) then
        PulseBlip(blip)
    end
end

exports('blips_pulse_blip', pulse_blip)
utils.blips.pulse_blip = pulse_blip

Example

--- Enable pulse on blip 1.
utils.blips.pulse_blip(1)

flash_blip()

Flashes a specified blip for a certain duration.

Function

local function flash_blip(blip, duration)
    if DoesBlipExist(blip) then
        BeginTextCommandSetBlipFlashes('STRING')
        AddTextComponentString(' ')
        EndTextCommandSetBlipFlashes(blip)
        Citizen.SetTimeout(duration * 1000, function()
            EndTextCommandSetBlipFlashes(blip)
        end)
    end
end

exports('blips_flash_blip', flash_blip)
utils.blips.flash_blip = flash_blip

Example

--- Flashes blip 1 for 5 seconds.
utils.blips.flash_blip(1, 5)

set_blip_route()

Sets a route to a blip on minimap.

Function

local function set_blip_route(blip, enable)
    if DoesBlipExist(blip) then
        SetBlipRoute(blip, enable)
    end
end

exports('blips_set_blip_route', set_blip_route)
utils.blips.set_blip_route = set_blip_route

Example

--- Set route to blip 1.
utils.blips.set_blip_route(1, true)

set_blip_priority()

Set the priority of a specified blip.

Function

local function set_blip_priority(blip, priority)
    if DoesBlipExist(blip) then
        SetBlipPriority(blip, priority)
    end
end

exports('blips_set_blip_priority', set_blip_priority)
utils.blips.set_blip_priority = set_blip_priority

Example

--- Set priority for blip 1.
utils.blips.set_blip_priority(1, 2)

remove_blip_by_label()

Removes a specified blip by its label.

Function

local function remove_blip_by_label(label)
    for blip_id, blip_data in pairs(created_blips) do
        if blip_data.label == label then
            remove_blip(blip_id)
        end
    end
end

exports('blips_remove_blip_by_label', remove_blip_by_label)
utils.blips.remove_blip_by_label = remove_blip_by_label

Example

--- Removes blip with label 'Blip Label'.
utils.blips.remove_blip_by_label('Blip Label')