Make use of our settings API

The settings API allows you to link your LUA variables to our settings system, providing an auto-generated user interface to modify any of your variables in real-time while your script is running.

Users can open the LUA Settings Hub to see all of the variables your script exposed and change them. They can save their own configuration and load it or delete it to go back to your provided default values. You can optionally call a function to load the user settings on each script start, more on that below.

Quick Overview

To integrate your script with our settings API, you will have to define a global settings table variable. Here is an example of a settings table defining some values, for clarity the full script is provided:

It may be obvious to some but the names here are freely choosable.

Of course "someInt" could be named anything you like and the same applies to any other entry in the settings table. Do not assume that you have to use the same naming as in these examples. The only thing it has to adhere to is Lua's naming convention (e.g. no spaces etc)

settings = {
    someInt = 50,
    someFloat = 5.5,
    someOtherFeature = true,
    name = "Bob",
    textColor = Vec4:new(1, 0, 0, 1)
}

function tick()
    draw.text(
        "someInt: " .. tostring(settings.someInt), 
        Vec2:new(200, 200), 
        Vec4:new(255, 0, 0, 255), 
        60, 
        "Verdana"
    )

    draw.text(
        "someFloat: " .. tostring(settings.someFloat), 
        Vec2:new(200, 260), 
        Vec4:new(255, 0, 0, 255), 
        60, 
        "Verdana"
    )

    draw.text(
        settings.name, 
          Vec2:new(200, 320), 
         settings.textColor, 
        60, 
        "Verdana"
     )    
end

engine.addEventListener("render", tick);

If you run the above script yourself you should see something similar to:

Opening the Settings Hub

In order to open the Lua Settings Hub, you'll have to create bind for it. You'll find all binds in the last tab under the Binds subtab, like so:

If you open the settings hub you'll see all the exported settings of our small example script, easily changable. Your script has to be running for it to show up in the Settings Hub.

Please click to enlarge for more detail

Saving & Loading

Users can change your variables in the hub and save them by clicking on the save symbol.

You can load the settings of a user directly upon the start of your script by simply calling loadSettings() after you defined the settings table, like so:

settings = {
    someInt = 50,
    someFloat = 5.5,
    someOtherFeature = true,
    name = "Bob",
    textColor = Vec4:new(1, 0, 0, 1)
}

loadSettings()

Make sure to call loadSettings() after you defined the settings table. If you were to call it before then Anvil would load the user settings and then your definition of the settings table would override the loaded settings again.

If the user has any settings saved it will load them into your settings table, otherwise use the default values you provided e.g. someInt would be 50 if no settings were found.

Advanced Usage

The settings API supports the following types:

• bool

• int

• float

• string

• Vec4 (color usage)

• callback function

Bool

A simple bool will be displayed as a checkbox in the Settings Hub

settings = {
    someOtherFeature = true
}

The only supported metadata for bools is the onChange handler. If you wish to run some code when the user clicks the checkbox, you can specify an onChange handler like in the below example:

function doSomeWork(newBoolState)
    print("State is now: " .. tostring(newBoolState))
end

settings = {
    someOtherFeature = {
        value = true,
        onChange = doSomeWork
    }
}

-- using the bool in your code: settings.someOtherFeature.value

Please click to enlarge for more detail

Int & Float

Ints and floats will be displayed as a number input respectively.

settings = {
    someInt = 50,
    someFloat = 5.5
}

The supported metadata for ints and floats are min and max and the onChange handler as seen above in the Bool section. To constrain the user to only inputting numbers in a certain range make use of the min and max metadata, like so:

settings = {
    someInt = {
        value = 50,
        min = 0,
        max = 100
    },
    someFloat = {
        value = 5.5,
        min = -180,
        max = 180
    }
}

Instead of a direct number input, the numbers will now be linked to sliders with your specified min and max values clamping the input to your desired range.

Please click to enlarge for more detail

String

Strings will be displayed as a simple text input.

settings = {
    name = "Bob"
}

The supported metadata for strings is the onChange handler as seen in the Bool section. If you want to run code when the user typed in a new character (e.g. changed the string at all) then do it like so and run the handling code in the onChange callback function:

function handleNameChange(newName)
    print("New name: " .. newName)
    -- do some work etc..
end

settings = {
    name = {
        value = "Bob",
        onChange = handleNameChange
    }
}

Please click to enlarge for more detail

Vec4 (color)

Vec4's will be displayed as a color input and are intended to be used for colors.

settings = {
    textColor = Vec4:new(1, 0, 0, 1)
}

If you click on the color square you can fully configure the color:

The supported metadata for is the onChange handler. Refer to the Bool or Int&Float section for details. The callback function will get passed the new color value (Vec4 type).

Function

A function will be displayed as a button. When the user clicks the button in the Settings Hub, your function will be executed.

function doSomething()
    print("doing some work...")
    -- do some work etc..
end

settings = {
    Activate = doSomething
}

Please click to enlarge for more detail

Extra

You can provide a "description" key in the settings table to have a description of what your script is doing. This is a good place to tell the user how your script should be used / what it does.