Plugin Settings

[Ratsch0k]

Plugins should be able to define settings which the user can change in the GUI in the plugin's details.

How changes to the settings are propagated to the plugin is yet to decide.

[Ratsch0k]

General Requirements

Plugins should be able to almost fully customize their settings page.
This means, they should be able to show text, sections, and various types of input fields.

The following selection of inputs should be possible:

• text field
• button
• checkbox
• switch
• radio button
• selection

During the runtime, plugins should be able to change either anything or dedicated fields to reflect changes or give feedback to the user.

[Ratsch0k]

Proposal 1

local settings = require("settings")

function onInstall()
    -- Create settings
    section = settings.newSection()
    text = section:newText("This is just an example setting")
    button = section:newButton("Button - callback")
    button:setCallback(function()
        print("Button pressed")
    end)

    -- Change components
    button:setCallback(function()
        print("Changed callback")
        text:setTexet("You clicked the button")
    end)

    button:disable()
    button:setText("New text")

    -- Remove components
    removableText = section:newText("Please remove this")
    section:remove(removableText)
end

To be able to allow for dynamic creation and user interaction, the plugin manager assigns a unique id to each component.
This settings tree could look like this:

{
  "type": "section",
  "id": "00000000-0000-0000-000000000001",
  "content": [
    {
      "type": "text",
      "id": "00000000-0000-0000-000000000002",
      "content": "This is just an example setting"
    },
    {
      "type": "button",
      "id": "000000-0000-0000-000000000003",
      "enabled": false,
      "content": "Button - callback"
    }
  ]
}

The FutureMod GUI can take this information and create the necessary UI components.
If the user interacts with an input, FutureMod uses the components UI to inform the engine about the user interaction.
IDs should be unique per plugin.
Thus, it must tell the engine about the plugin and the input component.

When clicking a button, this interaction could look like this:

POST /plugin/<name>/settings

{
  "component": "button",
  "id": "000000-0000-0000-000000000002",
  "event": "click"
}

To allow the plugin to change the settings dynamically, FutureMod must fetch the settings in a regular interval.
Using websockets might be a bit to overkill.

The simple endpoint GET /plugin/<name>/settings could be used for this.

Discussion

This proposal is relatively straight forward to implement and the lua API corresponds tightly to the rust implementation.
However, it is slightly verbose and requires the developer to keep track of all components.
But it also allows the developer to modify settings in any other plugin function.
For example, if the developer wants to change some text in response to a game event they can simply use the button's variable.

For now, this is the best solution.

[Ratsch0k]

Proposal 2

The general interaction system and component tree is mostly the same as in proposal 1.
The significant difference to the first proposal is the p.lugin developer experience.
Instead of manually creating each component, the user can use one function call to create the entire settings page.

local settings = require("settings")

function onInstall()
    settings.create({
        type="section",
        id="main-section",
        content={
            {
                type="text",
                content="This is just an example settings"
            },
            {
                type="button",
                content="Button - callback",
                id="button",
                callback=function()
                    print("Button pressed")
                end
            },
        }
    })

    -- Change components
    button = settings.get("button")
    button:disable()
    button:setCallback(function()
        print("New callback")
    end)
end

The interaction mechanism is very similar to the first proposal.
However, the developer can manually set the component's id.
They can use the id to fetch a component.
Otherwise, the engine assigns a random ID to a component.

Discussion

This proposal is less verbose than the first proposal but changing settings after their creation become much more difficult.

[Ratsch0k]

Proposal 3

Somewhat of a hybrid between proposal 1 and 2.
Settings are created with one single function call, but the components can be created beforehand.

local settings = require("settings")

function onInstall()
    button = settings.Button("Button - callback")
    button:setCallback(function()
        print("Button pressed")
    end)

    settings.create({
        settings.Text("This is just an example setting"),
        button,
    })

    -- Change component
    button:disable()
    button:setText("New text")
    button:setCallback(function()
        print("New callback")
    end)
end

This proposal has to address the issue of what happens if the developer uses the same component two times.
For example:

button = settings.Button("Test")

settings.create({
  button,
  button,
})

Does the API reject this? Or will it create two copies of the same button only with different IDs? What happens with assigned callback?

Discussion

While I really like this approach, the mentioned issue is hard to solve intuitively.
Otherwise, it is even less verbose than proposal 2 while still providing easy component modification like proposal 1.

[Ratsch0k]

Proposal 4

A completely different approach.
The developer has less flexibility and can only define a configuration schema with default values.
Based on this, FutureMod creates a fitting UI.
When the user changes a value, the plugin is informed about this change via a specific event.

      local flag = false
  
      function onInstall()
          settings.create({
              exampleFlag={
                  type="boolean",
                  default=false,
                  description="Some example flag"
              }
          })
      end
  
      function onSettingsChange(event)
          if (event.target == "exampleFlag") then
              flag = event.value
          end
      end

Discussion

In contrast to proposals 1-3 this proposal is much more restrictive.
It does not allow the developer to show arbitrary text or button and only focuses on the settings themselves.
Furthermore, updating specific components is not easily possible.
Extending this to allow for buttons and text feels somewhat clunky.

[Ratsch0k]

Selected proposal

The selected proposal will be proposal 3.

The issue regarding reusing component variables will be implemented as a feature with additional functionality. Developers can create template components and use them during the settings creation. To ease this use case, modification function, like setCallback will return the button itself. The only case where reusing a component is a problem is when the user manually sets an ID or when they change the variable afterwards. When the developer sets a manual ID, the call to settings.create() errors. To combat the second issue, the components are slightly changed. Instead of representing the actual components themselves, they are component builders. This means that the developer can use the component builder to build their components and the settings page will use it to actually create the component. If the developer changes a component after calling settings.create(), the actual component will not get changed. Otherwise, the behavior is really unclear when the component is reused. This also means, that for changing the a component after creating the settings, the developer must use a similar process as in proposal 2.

To avoid issues with the component variable,

With this change the following usage is possible:

disabledButton = settings.Button("Template"):disabled()

settings.create({
  disabledButton
    :onClick(function()
      print("First button called")
    end)
    :withText("First"),
  disabledButton
    :withText("Second")
    :withID("second-button"),
})

secondButton = settings.get("second-button")
secondButton:onClick(function()
  print("Clicked second button")
end)