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.

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

MissionUI.updateIcon(id, opts)

Update an icon by ID. Pass only the options you want to change.

MissionUI.removeIcon(id)

Remove one icon.

MissionUI.removeAllIcons()

Remove all icons.

---

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
    local icon1 = MissionUI.addIcon({
        dict = "BLIPS",
        name = "blip_ambient_gang_leader",
        color = { 255, 255, 255, 255 },
    })
    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 } })

    -- 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)