Create and manage on-screen paint overlays with dynamic content.

paint:new_builder() -> PaintBuilder

Create a new paint builder for constructing overlays.

Returns:

• PaintBuilder - Builder instance

Example:

local builder = paint:new_builder()
builder:add_string("Health", function()
    return combat:current_health() .. "/" .. combat:max_health()
end)
local paint_id = builder:build()

---

paint:hide(id: string) -> ()

Hide a paint overlay.

Parameters:

• id (string) - Paint ID from build()

---

paint:show(id: string) -> ()

Show a paint overlay.

Parameters:

• id (string) - Paint ID

---

paint:remove(id: string) -> ()

Remove a paint overlay completely.

Parameters:

• id (string) - Paint ID

---

paint:update_rows(id: string, rows: table) -> ()

Update paint rows dynamically.

Parameters:

• id (string) - Paint ID
• rows (table) - Array of row data

---

paint:update_simple_rows(id: string, strings: table) -> ()

Update rows from simple string array.

Parameters:

• id (string) - Paint ID
• strings (table) - Array of strings

---

builder:add_string(label: string, get_value_func: function?) -> PaintBuilder

Add string row with optional dynamic value.

Parameters:

• label (string) - Row label
• get_value_func (function, optional) - Function returning value

Returns:

• PaintBuilder - Self for chaining

Example:

builder:add_string("Player", function()
    local p = players:local_player()
    return p and p:name() or "Unknown"
end)

---

builder:add_shared_string(shared_string) -> PaintBuilder
builder:add_labeled_shared_string(label: string, shared_string) -> PaintBuilder

Add a row that displays a shared string (see shared:string(key)). Pass the shared string variable. The value is read from the shared store at render time, so it can update more than once per poll (e.g. when set from event handlers or other threads).

Parameters:

• shared_string - The shared string from shared:string("key")
• label (string) - Row label for add_labeled_shared_string

Returns:

• PaintBuilder - Self for chaining

Example:

local status = shared:string("paint_status")
builder:add_shared_string(status)
builder:add_labeled_shared_string("Status:", status)

---

builder:track_skill(skill: string) -> PaintBuilder

Add skill XP tracker.

Parameters:

• skill (string) - Skill name

Returns:

• PaintBuilder - Self for chaining

---

builder:track_item(filter: ItemFilter, label: string, per_hour?: boolean) -> PaintBuilder

Track quantity changes for items matching the filter. Automatically subscribes to inventory change events and displays the cumulative gain/loss count.

Parameters:

• filter (ItemFilter) - Item filter to match items (see Filters Guide)
• label (string) - Display label for the tracker
• per_hour (boolean, optional) - Whether to show per-hour rate (default: false)

Returns:

• PaintBuilder - Self for chaining

Display Format:

• Without per_hour: Label: +123 or Label: -45
• With per_hour: Label: +123 (456/hr)

Example:

-- Track logs by name
builder:track_item({name = "Logs"}, "Logs", true)

-- Track all runes
builder:track_item({name_contains = "rune"}, "Runes", true)

-- Track specific item IDs
builder:track_item({ids = {995, 996}}, "Coins")

-- Track with complex filter
builder:track_item({
    name_contains = "ore",
    min_stack = 1
}, "Ores", true)

---

builder:add_counter(label: string, initial: number?) -> PaintBuilder

Add counter row.

Parameters:

• label (string) - Counter label
• initial (number, optional) - Initial value

Returns:

• PaintBuilder - Self for chaining

---

builder:add_progress_bar(label: string, current: number, max: number) -> PaintBuilder

Add progress bar row.

Parameters:

• label (string) - Bar label
• current (number) - Current value
• max (number) - Maximum value

Returns:

• PaintBuilder - Self for chaining

---

builder:update_counter(label: string, value: number) -> ()

Update a counter previously added with add_counter (matched by label).

---

builder:with_position(x: number, y: number) -> PaintBuilder

Set paint position.

Parameters:

• x (number) - X coordinate
• y (number) - Y coordinate

Returns:

• PaintBuilder - Self for chaining

---

builder:with_size(width: number, height: number) -> PaintBuilder

Set paint size.

Parameters:

• width (number) - Width in pixels
• height (number) - Height in pixels

Returns:

• PaintBuilder - Self for chaining

---

builder:with_anchor(anchor: string) -> PaintBuilder

Set anchor point.

Parameters:

• anchor (string) - "top_left", "top_right", "bottom_left", "bottom_right", "center"

Returns:

• PaintBuilder - Self for chaining

---

builder:with_text_size(size: number) -> PaintBuilder

Set default text size.

---

builder:with_background_color(r: number, g: number, b: number, a?: number) -> PaintBuilder

Set background color (defaults: rgba(0,0,0,180)).

---

builder:with_text_color(r: number, g: number, b: number, a?: number) -> PaintBuilder

Set text color (defaults: rgba(255,255,255,255)).

---

builder:without_drag() -> PaintBuilder

Disable dragging.

---

builder:without_minimize() -> PaintBuilder

Disable minimize button.

---

builder:build() -> string

Build and register the paint overlay.

Returns:

• string - Paint ID for later reference

---

local function create_item_tracking_paint()
    local builder = paint:new_builder()
    
    -- Track logs with per-hour rate
    builder:track_item({name = "Logs"}, "Logs", true)
    
    -- Track all runes
    builder:track_item({name_contains = "rune"}, "Runes", true)
    
    -- Track ores
    builder:track_item({name_contains = "ore"}, "Ores", true)
    
    builder:with_position(10, 10)
    
    return builder:build()
end

---

local function create_status_paint()
    local builder = paint:new_builder()
    
    builder:add_string("Status", "Running")
    builder:add_string("Runtime", function()
        return os.date("%H:%M:%S")
    end)
    
    builder:with_position(10, 10)
    builder:with_anchor("top_left")
    
    return builder:build()
end

local paint_id = create_status_paint()

---

local function create_combat_paint()
    local builder = paint:new_builder()
    
    builder:add_string("HP", function()
        return combat:current_health() .. "/" .. combat:max_health()
    end)
    
    builder:add_string("Prayer", function()
        return prayer:prayer_points() .. "/" .. prayer:max_prayer_points()
    end)
    
    builder:add_progress_bar("Health %", 
        combat:current_health(), 
        combat:max_health()
    )
    
    builder:with_position(10, 100)
    
    return builder:build()
end

---

• Filters Guide - Item filtering for track_item
• Logger API - Logging messages
• Stats API - Script statistics