Script UI Configuration

The Script UI Configuration system allows scripts to define custom UI forms for user input. This provides a rich set of components for creating complex configuration interfaces that users interact with before starting your script.

What is Script UI Configuration?

Script UI Configuration lets you create custom configuration forms that appear when users load your script. Instead of hardcoding settings, users can configure:

• Basic inputs: Text fields, numbers, checkboxes, dropdowns
• Complex data: Tables with editable cells, multi-select lists
• Interactive elements: Buttons that trigger callbacks, dynamic updates
• Organized layouts: Tabs, sections, grids for complex configurations

Basic Concepts

Configuration Schema

Your script defines a config_schema table that describes the UI:

config_schema = {
    version = "1.0",
    layout = {
        type = "vstack",
        children = {
            {
                type = "select",
                id = "location",
                label = "Mining Location",
                props = {
                    options = {
                        {value = "varrock", label = "Varrock Mine"},
                        {value = "lumbridge", label = "Lumbridge Mine"}
                    },
                    default = "varrock"
                }
            },
            {
                type = "checkbox",
                id = "use_bank",
                label = "Use Banking",
                props = {default = true}
            }
        }
    }
}

Accessing Configuration Values

When the user clicks "Start", the configuration values are passed to your on_start function:

function script:on_start(config)
    local location = config.location  -- "varrock" or "lumbridge"
    local use_bank = config.use_bank   -- true or false
    
    logger:info("Starting at: " .. location)
    return true
end

Common Use Cases

Simple Settings

For basic scripts, a simple form is enough:

config_schema = {
    version = "1.0",
    layout = {
        type = "vstack",
        children = {
            {
                type = "number",
                id = "quantity",
                label = "How many items?",
                props = {min = 1, max = 1000, default = 100}
            },
            {
                type = "checkbox",
                id = "enable_breaks",
                label = "Take breaks",
                props = {default = false}
            }
        }
    }
}

Organized with Tabs

For complex scripts, organize settings into tabs:

config_schema = {
    version = "1.0",
    layout = {
        type = "tabs",
        children = {
            {
                type = "section",
                label = "General",
                children = {
                    -- General settings here
                }
            },
            {
                type = "section",
                label = "Advanced",
                children = {
                    -- Advanced settings here
                }
            }
        }
    }
}

Conditional Fields

Show/hide fields based on other selections:

{
    type = "checkbox",
    id = "enable_breaks",
    label = "Enable Breaks",
    props = {default = false}
},
{
    type = "number",
    id = "break_interval",
    label = "Break Interval (minutes)",
    visible = {
        field = "enable_breaks",
        operator = "equals",
        value = true
    },
    props = {min = 5, max = 120, default = 30}
}

Tables with Editable Cells

Let users configure multiple items in a table:

{
    type = "table",
    id = "item_config",
    label = "Item Configuration",
    props = {
        keys = {"name"},
        columns = {
            {key = "name", label = "Item"},
            {
                key = "quantity",
                label = "Quantity",
                component = {
                    type = "number",
                    props = {min = 1, max = 1000, default = 1}
                }
            },
            {
                key = "enabled",
                label = "Enabled",
                component = {
                    type = "checkbox",
                    props = {default = true}
                }
            }
        },
        data = {
            {name = "Iron ore", quantity = 10, enabled = true},
            {name = "Coal", quantity = 5, enabled = false}
        },
        selection_mode = "multiple"
    }
}

Best Practices

Organization

• Use tabs for scripts with many settings
• Group related fields in sections
• Provide clear labels and descriptions for all fields

User Experience

• Set sensible defaults so users can start quickly
• Use conditional visibility to hide irrelevant options
• Validate input with validation rules to prevent errors

Performance

• Keep schemas simple - complex nested structures can be slow to render
• Use dynamic callbacks sparingly - they're called on every change

Example: Complete Configuration

config_schema = {
    version = "1.0",
    layout = {
        type = "tabs",
        children = {
            {
                type = "section",
                label = "General",
                children = {
                    {
                        type = "select",
                        id = "location",
                        label = "Mining Location",
                        description = "Choose where to mine",
                        props = {
                            options = {
                                {value = "varrock_east", label = "Varrock East Mine"},
                                {value = "varrock_west", label = "Varrock West Mine"},
                                {value = "mining_guild", label = "Mining Guild"}
                            },
                            default = "varrock_east"
                        }
                    },
                    {
                        type = "checkbox",
                        id = "use_bank",
                        label = "Use Banking",
                        description = "Bank ores when inventory is full",
                        props = {default = true}
                    }
                }
            },
            {
                type = "section",
                label = "Advanced",
                children = {
                    {
                        type = "grid",
                        props = {columns = 2},
                        children = {
                            {
                                type = "number",
                                id = "min_delay",
                                label = "Minimum Delay (ms)",
                                props = {min = 50, max = 5000, default = 600}
                            },
                            {
                                type = "number",
                                id = "max_delay",
                                label = "Maximum Delay (ms)",
                                props = {min = 50, max = 5000, default = 1200}
                            }
                        }
                    }
                }
            }
        }
    }
}

function script:on_start(config)
    logger:info("Location: " .. config.location)
    logger:info("Use bank: " .. tostring(config.use_bank))
    logger:info("Delays: " .. config.min_delay .. "-" .. config.max_delay .. "ms")
    return true
end

Next Steps

• Script UI Configuration API Reference - Complete API documentation with all components, properties, and examples
• Script Structure and Setup - Learn how to structure your scripts
• Events and Shared State - Handle configuration changes dynamically