Plugin settings

[Lobby]

Plugins can add custom entries to the game's settings menu by defining a script:settings() function in a Lua script. This function returns a list of settings, including their names, values, and callbacks. The following example demonstrates the available setting types and how to store their values.

image.png

Code: Select all

-- We define the local variable for our settings table here so that our functions can see it
local settings

function script:init()
  -- Let's get a storage table and initialize values that are nil
  settings = Util.optStorage(TheoTown.getStorage(), self:getDraft():getId()..':settings')
  settings.someBool = settings.someBool == nil and true or settings.someBool
  settings.someInt = settings.someInt or 1
  settings.someNamedInt = settings.someNamedInt or 3
  settings.someString = settings.someString or 'Xyz'
  settings.someGenericText = settings.someGenericText or 'Hello World'
end

-- This function will be called whenever the game enters or refreshes the settings view.
-- The result is expected to be a table of tables that contain settings.
function script:settings()
  return {
    -- Boolean setting
    {
      name = 'Bool setting',
      value = settings.someBool,
      onChange = function(newState) settings.someBool = newState end
    },
    -- Integer setting
    {
      name = 'Integer setting',
      value = settings.someInt,
      values = {1, 2, 3},
      onChange = function(newState) settings.someInt = newState end
    },
    -- Integer setting with custom names
    {
      name = 'Named integer setting',
      value = settings.someNamedInt,
      values = {1, 2, 3},
      valueNames = {'A', 'B', 'C'},
      onChange = function(newState) settings.someNamedInt = newState end
    },
    -- Setting with multiple string options
    {
      name = 'Some strings',
      value = settings.someString,
      values = {'Abc', 'Xyz', '123'},
      onChange = function(newState) settings.someString = newState end
    },
    -- Editable text setting
    {
      name = 'Generic text',
      desc = 'Here you can enter a text:',
      value = settings.someGenericText,
      onChange = function(newState) settings.someGenericText = newState end,
      onReset = function() settings.someGenericText = 'Reset was called' end
    },
    -- Hint text: no onChange callback
    {
      name = 'You can customize these settings.'
    },
    -- Colored link: no value or values
    {
      name = 'Reset generic text',
      color = 'FFAA33',
      onChange = function(_, rebuild)
        settings.someGenericText = 'Hello World'
        rebuild() -- Refresh the settings UI
      end
    }
  }
end

The settings category is labeled with the name of the plugin or file that provides it. For plugins from the Plugin Store, the plugin's name is shown. If the script defines an icon frame, it is used as the category icon.

Update for version 1.12.98
The onChange callback now receives a second argument, rebuild, which can be called to refresh the settings UI. This is useful when a setting opens another dialog, such as a color picker, and the UI needs to reflect changes made there. Existing onChange callbacks continue to work without modification.

Additional features:

• Settings without an onChange callback are displayed as hint text.
• Settings without value and values are displayed as clickable links that trigger onChange.
• Links can be assigned a custom color using the color property, specified as a hex color string.
• If the script owning the draft defines an "icon frame", it is used as the icon for the settings category.

[ian`]

What is the Generic Text have same functions with command (console)?

Show

Screenshot_20200709-072150_60.png

Screenshot_20200709-072203_60.png

[Lobby]

It's like the input dialog for rules in online mode. You use it to edit some sort of text.

[ian`]

I see. Because it looks strange in the settings tab.

[ian`]

What is it code correct to set the default boolean value settings to be false? Because when i'm use that code, bad argument issue occurs.

Code: Select all

settings.someBool = settings.someBool == nil and false or settings.someBool

Show

Screenshot_20200710-063904.png

Edit---
I think the problem is solved. but i have one question, what for is '== nil and true'?

[Lobby]

Since nil is also considered false in Lua I have to check if it is actually nil before applying a default value. I have to ensure that the variable contains true or false because the game expects a boolean value in order to show the checkbox.

Although nil is considered as false, it is not the same as false, meaning that nil == false is false.

Code: Select all    Reset

local function foo(var)
  print(var == nil and true or var)
end

foo(nil)    -- Should evaluate to the "default value" true
foo(false)  -- Should be false
foo(true)   -- Should be true

Lua editor

Run

Output: Select all

...

[erksmit]

is it possible to use a textbox or slider as a setting? i want the user to be able to enter any number value they want

[ian`]

is it possible to use a textbox or slider as a setting? i want the user to be able to enter any number value they want

i think you only can use like generic text (in this case textField) and add more vars on the onChange options.

Code: Select all    Reset

function script:settings()
  return{
    {
      name = 'Generic text',
      -- This description will be shown when user enters a new text
      desc = 'Here you can enter a text:',
      value = settings.someGenericText,
      onChange = function(newState)
        settings.someGenericText = newState
        vars1 = newstate -- optional variable to be changed with new value
      end
    }
  }
end

Lua editor

Run

Output: Select all

...

[Hadestia]

Is it really possible to add "hidden":true for all the ingame drafts if a made plugin settings for it?