Plugin settings

Plugin settings

A plugin declares its settings. ProLeak saves the values between sessions and gives the plugin a Settings button in the Mods menu with a form built from the declarations.

from proleak import settings

refresh = settings.add("refresh_seconds", 60, min=10, max=600, label="Refresh every",
                       subtitle="In seconds")
greeting = settings.add("greeting", "", label="Greeting",
                        help="A line said in your chat at the start of each game")
style = settings.add("style", "small", choices=["small", "large"])
lanes = settings.add("lanes", ["left"], choices=["left", "middle", "right"], label="Lanes")
tint = settings.add("tint", "#9146ff", type="color", label="Tint")
key = settings.add("show_key", "F6", type="key", label="Show key")


@refresh.on_change
def reschedule(value):
    ...

Contents

• Declaring a setting
• Reading and changing values
• Where values are saved
• Settings in plugin.yml

Declaring a setting

settings.add(key, default, type=None, label=None, subtitle=None, help=None,
             min=None, max=None, choices=None)

Declare settings when the plugin loads, in the module body or in on_load. The type follows the default (bool, int, float or text) unless type names one of these:

type	Value	Form control
"choice"	one of choices	a drop-down
"multi"	a list of any of choices, in their order	a drop-down with ticks
"color"	#rrggbb	a color picker
"key"	a Unity key name (V, F12, PageUp)	a hotkey button: click it, press a key

Argument	Effect
choices	The values of a choice. With a list default it makes a "multi", whose choices cannot contain a comma.
min, max	Bound a number.
label	The name the form shows.
subtitle	A short line under the label, in smaller grey text.
help	Longer text in a "?" box beside the label.

In the form, a right click on a control puts it back to its default.

Reading and changing values

Code	Does
setting.value	The saved value.
setting.value = x	Validates and saves a new value (ValueError when it is out of range).
@setting.on_change	Calls fn(value) after the setting changes, from code or from the Mods menu.
settings.get(key), settings.set(key, value), settings.as_dict()	The same by key.
@settings.on_change	Calls fn(key, value) after any of the plugin's settings changes.

With on_change a plugin applies a change at once, during a game too.

Tip

Pass the setting itself

Where the UI takes a value, such as a widget's bind=, pass the setting rather than setting.value. The UI then follows every change.

Where values are saved

ProLeak saves the values to ProLeak/config/<id>.yml, and keeps a saved value when the plugin declares the setting again in a later session. A hand-edited value of the wrong type or out of range falls back to its default with a warning, and the plugin still loads.

Settings in plugin.yml

Settings can also be declared in plugin.yml under settings:, with the same type, default, label, subtitle, help, min, max and values (the choices):

settings:
  refresh_seconds: {type: int, min: 10, max: 600, default: 60, label: Refresh every}
  greeting:        {type: string, default: "", label: Greeting}
  style:           {type: choice, values: [small, large], default: small}
  lanes:           {type: multi, values: [left, middle, right], default: [left]}

A multi-select default there is a YAML list. settings.get, settings.set, settings.as_dict() and ctx.settings work for settings declared either way.

---

Previous: Handling events | Next: User interface