> For the complete documentation index, see [llms.txt](https://docs.anvil.team/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.anvil.team/user-settings/make-use-of-our-settings-api.md). # 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: {% hint style="info" %} 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) {% endhint %} ```lua 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.

## 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: ```lua settings = { someInt = 50, someFloat = 5.5, someOtherFeature = true, name = "Bob", textColor = Vec4:new(1, 0, 0, 1) } loadSettings() ``` {% hint style="info" %} 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. {% endhint %} 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 ```lua 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: ```lua 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 ```

### Int & Float Ints and floats will be displayed as a number input respectively. ```lua 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: ```lua 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.

### String Strings will be displayed as a simple text input. ```lua 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: ```lua function handleNameChange(newName) print("New name: " .. newName) -- do some work etc.. end settings = { name = { value = "Bob", onChange = handleNameChange } } ```

### 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. ```lua function doSomething() print("doing some work...") -- do some work etc.. end settings = { Activate = doSomething } ```

### 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.