Paint API

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

Functions

new_builder

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

---

hide

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

Hide a paint overlay.

Parameters:

Parameter	Type	Required	Description
id	i32	Yes	Paint ID from build()

---

show

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

Show a paint overlay.

Parameters:

Parameter	Type	Required	Description
id	i32	Yes	Paint ID

---

remove

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

Remove a paint overlay completely.

Parameters:

Parameter	Type	Required	Description
id	i32	Yes	- Paint ID

---

update_rows

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

Update paint rows dynamically.

Parameters:

Parameter	Type	Required	Description
id	i32	Yes	Paint ID
rows	table	Yes	Array of row data

---

update_simple_rows

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

Update rows from simple string array.

Parameters:

Parameter	Type	Required	Description
id	i32	Yes	Paint ID
strings	table	Yes	Array of strings

---

update_counter

paint:update_counter(id: i32, label: string, value: number) -> ()

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

Parameters:

Parameter	Type	Required	Description
id	i32	Yes	Paint ID
label	string	Yes	Counter label
value	number	Yes	New counter value

---

update_progress_bar

paint:update_progress_bar(id: i32, label: string, current: number, max: number) -> ()

Update a progress bar previously added with add_progress_bar (matched by label).

Parameters:

Parameter	Type	Required	Description
id	i32	Yes	Paint ID
label	string	Yes	Progress bar label
current	number	Yes	Current progress value
max	number	Yes	Maximum progress value

---

PaintBuilder Methods

add_string

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

Add string row with optional dynamic value.

Parameters:

Parameter	Type	Required	Description
label	string	Yes	Row label
get_value_func	function	No	Function returning value as string

Returns:

• PaintBuilder - Self for chaining

Example:

-- Static text
builder:add_string("My Script v1.0")

-- Dynamic text
builder:add_string("Current HP", function()
    local player = players:local_player()
    return player and tostring(player:health()) or "N/A"
end)

---

track_skill

builder:track_skill(skill: string) -> PaintBuilder

Add skill XP tracker that shows XP gained and XP per hour.

Parameters:

Parameter	Type	Required	Description
skill	string	Yes	Name of the skill (e.g., "Mining", "Woodcutting")

Returns:

• PaintBuilder - Self for chaining

Display format: "Skill: +123 XP (456 XP/hr)"

Example:

builder:track_skill("Mining")
builder:track_skill("Smithing")

---

track_item

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:

Parameter	Type	Required	Description
filter	ItemFilter	Yes	Item filter to match items (see Filters Guide)
label	string	Yes	Display label for the tracker
per_hour	boolean	No	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)

---

add_counter

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

Add counter row that can be updated programmatically.

Parameters:

Parameter	Type	Required	Description
label	string	Yes	Counter label
initial	number	No	Initial value (default: 0)

Returns:

• PaintBuilder - Self for chaining

Example:

builder:add_counter("Actions Performed", 0)

-- Update later
paint:update_counter(paint_id, "Actions Performed", 42)

---

add_progress_bar

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

Add progress bar row.

Parameters:

Parameter	Type	Required	Description
label	string	Yes	Progress bar label
current	number	Yes	Current progress value
max	number	Yes	Maximum progress value

Returns:

• PaintBuilder - Self for chaining

Example:

builder:add_progress_bar("Progress", 50, 100)

-- Update later
paint:update_progress_bar(paint_id, "Progress", 75, 100)

---

with_position

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

Set paint position.

Parameters:

Parameter	Type	Required	Description
x	number	Yes	X coordinate in pixels
y	number	Yes	Y coordinate in pixels

Returns:

• PaintBuilder - Self for chaining

Default: (10, 10)

---

with_size

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

Set paint size (minimum dimensions).

Parameters:

Parameter	Type	Required	Description
width	number	Yes	Minimum width in pixels
height	number	Yes	Minimum height in pixels

Returns:

• PaintBuilder - Self for chaining

Default: (300, 100)

---

with_anchor

builder:with_anchor(anchor: string) -> PaintBuilder

Set anchor point that determines how the paint is positioned relative to the game window.

Parameters:

Parameter	Type	Required	Description
anchor	string	Yes	Anchor point

Valid values:

• "top_left" - Anchor to top-left corner (default)
• "top_right" - Anchor to top-right corner
• "bottom_left" - Anchor to bottom-left corner
• "bottom_right" - Anchor to bottom-right corner
• "center" - Anchor to center of screen

Returns:

• PaintBuilder - Self for chaining

---

with_text_size

builder:with_text_size(size: number) -> PaintBuilder

Set font size for all text in the paint.

Parameters:

Parameter	Type	Required	Description
size	number	Yes	Font size in points

Returns:

• PaintBuilder - Self for chaining

Default: 12.0

---

with_background_color

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

Set background color of the paint window.

Parameters:

Parameter	Type	Required	Description
r	number	Yes	Red component (0-255)
g	number	Yes	Green component (0-255)
b	number	Yes	Blue component (0-255)
a	number	No	Alpha/transparency (0-255, where 0 is fully transparent)

Returns:

• PaintBuilder - Self for chaining

Default: rgba(0, 0, 0, 180) - Semi-transparent black

---

with_text_color

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

Set default text color for the paint.

Parameters:

Parameter	Type	Required	Description
r	number	Yes	Red component (0-255)
g	number	Yes	Green component (0-255)
b	number	Yes	Blue component (0-255)
a	number	No	Alpha/transparency (0-255)

Returns:

• PaintBuilder - Self for chaining

Default: rgba(255, 255, 255, 255) - White

---

without_drag

builder:without_drag() -> PaintBuilder

Disable the ability to drag and reposition the paint window.

Returns:

• PaintBuilder - Self for chaining

Default: Draggable is enabled

---

without_minimize

builder:without_minimize() -> PaintBuilder

Disable the minimize button on the paint window.

Returns:

• PaintBuilder - Self for chaining

Default: Minimize button is enabled

---

build

builder:build() -> i32

Build and register the paint overlay.

Returns:

• i32 - Paint ID for later reference

---

Common Patterns

Item Tracking Paint

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

---

Script Status Paint

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

---

Combat 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

---

Comprehensive Mining Script Paint

-- Create a comprehensive mining script paint
local paint_id = paint:new_builder()
    -- Position and appearance
    :with_position(10, 10)
    :with_size(350, 300)
    :with_anchor("top_left")
    :with_text_size(13.0)
    :with_background_color(15, 15, 15, 220)
    :with_text_color(220, 220, 220, 255)

    -- Static header
    :add_string("Mining Script v2.1")
    :add_string("")  -- Blank line

    -- Skill tracking
    :track_skill("Mining")

    -- Item tracking
    :track_item({name = "Iron ore"}, "Iron ore", true)
    :track_item({name = "Coal"}, "Coal", true)

    -- Custom counters
    :add_counter("Trips Completed", 0)
    :add_counter("Ores Mined", 0)

    -- Progress bar
    :add_progress_bar("Inventory", 0, 28)

    -- Dynamic status
    :add_string("Status", function()
        return get_current_status()  -- Your status function
    end)

    -- Build the paint
    :build()

-- Update paint during script execution
function update_ui()
    local player = players:local_player()
    if player then
        local inv_count = inventory:count()
        paint:update_progress_bar(paint_id, "Inventory", inv_count, 28)
    end
end

---

Default Values Reference

Paint Defaults

{
    x = 10,
    y = 10,
    min_width = 300,
    min_height = 100,
    text_size = 12.0,
    anchor = "top_left",
    bg_color = {r = 0, g = 0, b = 0, a = 180},
    text_color = {r = 255, g = 255, b = 255, a = 255},
    visible = true,
    draggable = true,
    minimizable = true
}

Progress Bar Defaults

{
    width = 200,
    height = 20,
    bar_color = {r = 0, g = 255, b = 0, a = 255},      -- Green
    bg_color = {r = 100, g = 100, b = 100, a = 255}    -- Gray
}

---

Best Practices

1. Paint Performance: Avoid updating paints too frequently (e.g., every tick). Update every 1-2 seconds for smooth performance.

2. Color Consistency: Use consistent color schemes across your paint UI for better user experience.

3. Descriptive Labels: Provide clear labels for all paint elements.

4. Progress Feedback: Use progress bars and counters to give users clear feedback on script execution.

5. Skill/Item Tracking: Use the built-in track_skill() and track_item() methods for automatic XP and item tracking rather than implementing manually.

---

Related APIs

• Paint Guide - Learn how to use Paint in your scripts
• Filters Guide - Item filtering for track_item
• Logger API - Logging messages
• Stats API - Script statistics