Mission UI

A Native mission HUD with timer, icons, and subtitle. Layout stacks dynamically based on visible sections. Uses aspect-ratio correction for consistent display across resolutions.

---

Get the module

local MissionUI = exports.bln_lib:missionUi()

---

API

Core

Method	Description
MissionUI.visible(show)	Show (true) or hide (false - State will still active). Call with no args to get current state.
MissionUI.isVisible()	Returns whether the UI is visible
MissionUI.destroy()	Full cleanup (stops timer, clears all, no callback)

---

Timer

MissionUI.startTimer(opts)

Start a countdown. UI shows automatically. When time reaches 0, UI hides and onEnd runs (if set).

Option	Type	Default	Description
time	number	60	Duration in seconds
lowTime	number	5	Seconds left before low-time color
onEnd	function	—	Called when timer reaches 0
font	number	6	Text font ID
timeColor	table	—	RGBA for normal time text
lowTimeColor	table	—	RGBA when time ≤ lowTime
bgColor	table	—	RGBA for timer background

MissionUI.stopTimer()

Pause the countdown. UI stays visible.

MissionUI.resumeTimer()

Resume the countdown from current value (after stopTimer).

MissionUI.endTimer()

Stop the countdown and hide the UI.

---

Subtitle

MissionUI.setSubtitle(opts)

Set or update subtitle. Use text = nil or text = "" to remove.

Option	Type	Default	Description
text	string	—	Subtitle text (nil or "" to remove)
color	table	—	RGBA
scale	number	0.35	Text scale
font	number	6	Font ID
x	number	0.5	Horizontal position

MissionUI.removeSubtitle()

Remove subtitle.

---

Icons

MissionUI.addIcon(opts) → id

Add an icon. Returns an ID for later updates. Up to 10 icons are shown at once; extra icons are queued (FIFO) and auto-shown when an active icon is removed.

Option	Type	Default	Description
dict	string	"BLIPS"	Texture dictionary
name	string	"blip_ambient_gang_leader"	Texture name
color	table	—	RGBA for icon
bgColor	table	—	RGBA for icon background
bgDict	string	—	Background texture dict
bgName	string	—	Background texture name
size	number | string	—	Size preset (xs, s, md, lg, xl, 2xl) or numeric value (ex: 0.03);
iconW	number	—	Icon width override
iconH	number	—	Icon height override
bgW	number	—	Background width override
bgH	number	—	Background height override

MissionUI.updateIcon(id, opts)

Update an icon by ID (active or queued). Pass only the options you want to change. Supports the same visual fields as addIcon (dict, name, color, bg*, size, iconW, iconH), where size can be a preset or numeric value and keeps default icon/background proportions.

MissionUI.removeIcon(id)

Remove one icon.

MissionUI.removeAllIcons()

Remove all icons.

MissionUI.setIconSpacing(value)

Set icon spacing with a simple normalized level or raw value.

values = 1, 2, 3, ....

MissionUI.setStartLineY(value)

Set where the first mission line starts on Y (vertical screen position).

values = 1, 2, 3, ....

---

Full example

local MissionUI = exports.bln_lib:missionUi()

-- Start mission with timer, subtitle, and objectives
function StartMission()
    -- 2-minute timer, low-time at 15 seconds, red when low
    MissionUI.startTimer({
        time = 120,
        lowTime = 15,
        timeColor = { 255, 255, 255, 255 },
        lowTimeColor = { 255, 80, 80, 255 },
        bgColor = { 0, 0, 0, 255 },
        onEnd = function()
            TriggerEvent("mission:failed", "Time expired")
        end,
    })

    -- Subtitle
    MissionUI.setSubtitle({
        text = "Escape before time runs out!",
        color = { 255, 255, 255, 255 },
    })

    -- Objective icons
    -- Normalized spacing: 2 = default, 1 = half, 3 = bigger gaps
    MissionUI.setIconSpacing(2)

    -- Start lines lower on screen (5 ~= around half)
    MissionUI.setStartLineY(5)

    local icon1 = MissionUI.addIcon({
        dict = "BLIPS",
        name = "blip_ambient_gang_leader",
        color = { 255, 255, 255, 255 },
        size = "lg",
        bgW = 0.034,
        bgH = 0.048,
    })
    local icon2 = MissionUI.addIcon({
        dict = "BLIPS",
        name = "blip_ambient_sheriff",
        color = { 255, 200, 100, 255 },
    })

    -- Update icon when objective completes
    MissionUI.updateIcon(icon1, {
        color = { 100, 255, 100, 255 },
        size = 0.024,
    })

    -- Update subtitle
    MissionUI.setSubtitle({ text = "1/2 objectives complete" })
end

-- Complete mission
function CompleteMission()
    MissionUI.endTimer()
    MissionUI.removeSubtitle()
    MissionUI.removeAllIcons()
end

-- Toggle UI visibility (e.g. when opening a menu)
MissionUI.visible(false)  -- hide
MissionUI.visible(true)   -- show
MissionUI.visible(not MissionUI.isVisible())  -- toggle

-- Pause/resume timer
MissionUI.stopTimer()
MissionUI.resumeTimer()

-- Cleanup on resource stop
AddEventHandler("onResourceStop", function(resourceName)
    if GetCurrentResourceName() == resourceName then
        MissionUI.destroy()
    end
end)