BLN Studio Docs - RedM Scripts

Meters Module ​

Image 1

The Meters module provides native RDR2 circular meters with support for:

  • Primary icon + progress value
  • Secondary icon layer
  • Overlay icon layer
  • Blink and pulse states
  • Dynamic meter IDs
  • Queueing when more than 8 meters are created

Getting Started ​

lua
local Meters = exports.bln_lib:missionMeterUi()

Basic Usage ​

Create a meter ​

lua
local meter = Meters.create({
    value = 0.35, -- 0.0 to 1.0
    color = "COLOR_YELLOW",
    blink = false,
    pulse = true,
    icon = {
        dict = "overhead",
        name = "overhead_ambient_hunter",
        color = "COLOR_YELLOW"
    }
})

local id = meter:getId()
print("Created meter id:", id)

Update using the meter object ​

lua
meter:update({ value = 0.5 })

Update a meter by ID ​

lua
Meters.update(1, {
    value = 0.8,
    color = "COLOR_RED",
    pulse = false
})

Create Options ​

Meters.create(options) supports:

  • value (number): meter fill from 0.0 to 1.0 (auto-clamped)
  • color or meterColor (string): meter ring color
  • blink (boolean): blink primary icon
  • pulse (boolean): pulse animation
  • visible (boolean): default true
  • enabled (boolean): default true
  • icon (table):
    • dict or txd (string)
    • name or txn (string)
    • color or imgColor (string)
  • secondary or secondaryIcon (table):
    • enabled (boolean)
    • dict/txd, name/txn, color/imgColor
  • overlay (table):
    • enabled (boolean)
    • dict/txd, name/txn, color/imgColor

Module Methods ​

Meters.create(options) ​

Creates a meter and returns a meter object.

If all native slots are busy (8 max visible), the new meter is queued automatically.

Meters.get(id) ​

Returns the meter object for this ID, or nil.

Meters.exists(id) ​

Returns true if meter exists.

Meters.update(id, patch) ​

Updates a meter by ID.

Returns:

  • true on success
  • false, "meter_not_found" if ID does not exist

Meters.setSecondary(id, options) ​

Enables/updates/disables secondary icon data for a meter.

Meters.setOverlay(id, options) ​

Enables/updates/disables overlay icon data for a meter.

Meters.destroy(id) ​

Destroys a meter by ID.

Returns:

  • true on success
  • false, "meter_not_found" if ID does not exist

Meters.destroyAll() ​

Destroys all active and queued meters.

Meters.count() ​

Returns current meter count.

Meters.getAllIds() ​

Returns sorted list of meter IDs.

Meters.getSnapshot(id) ​

Returns a snapshot table for a meter, or nil.

Meters.getAllSnapshots() ​

Returns a snapshot array of all meters.

Meter Object Methods ​

Methods available on the object returned by Meters.create(...):

  • meter:getId()
  • meter:isQueued()
  • meter:getSnapshot()
  • meter:update(patch)
  • meter:setSecondary(options)
  • meter:clearSecondary()
  • meter:setOverlay(options)
  • meter:clearOverlay()
  • meter:show()
  • meter:hide()
  • meter:enable()
  • meter:disable()
  • meter:destroy()

Secondary and Overlay Behavior ​

lua
-- Disable secondary
meter:setSecondary({ enabled = false })

-- Disable overlay
meter:setOverlay({ enabled = false })

-- Also valid: nil disables
meter:setSecondary(nil)
meter:setOverlay(nil)

Calling setSecondary(...) or setOverlay(...) again updates existing values.

Queue and Slot Behavior ​

  • Native UI has 8 visible meter slots.
  • Additional meters are queued (FIFO).
  • When a visible meter is removed, the next queued meter is promoted.
  • Active meters are compacted in stable left-to-right order.

Example:

  • Create 1..9
  • 1..8 visible, 9 queued
  • Remove 1
  • Visible order becomes 2..9 (with 9 at the end)

Example: Full Flow ​

lua
local Meters = exports.bln_lib:missionMeterUi()

local meter = Meters.create({
    value = 0.2,
    color = "COLOR_GREEN",
    icon = {
        dict = "overhead",
        name = "overhead_ambient_hunter",
        color = "COLOR_GREEN"
    }
})

if meter then
    meter:setSecondary({
        enabled = true,
        dict = "overhead",
        name = "overhead_generic_arrow",
        color = "COLOR_RED"
    })

    meter:update({ value = 0.9, pulse = true })

    Wait(5000)
    meter:destroy()
end