API Plugin settings

Plugin settings

Import	from proleak import settings

Plugin settings: declared with add (or in plugin.yml), saved between sessions and editable from the plugin's Settings form in the Mods menu.

Classes

Class
Settings	Settings of one plugin (ctx.settings in on_load).
Setting	One setting the plugin declared with add.

Functions

Returns	Function
Setting	add(key: str, default: bool | int | float | str | list[str], *, type: str | None = None, label: str | None = None, subtitle: str | None = None, help: str | None = None, min: float | None = None, max: float | None = None, choices: list[str] | None = None)	Declare a setting of the calling plugin and return it as a Setting.
object	get(key: str, default: object = None)	Value of key for the calling plugin.
None	set(key: str, value: object)	Set key for the calling plugin.
dict[str, object]	as_dict()	All settings of the calling plugin.
Callable[[str, object], None]	on_change(fn: Callable[[str, object], None])	Decorator: call fn(key, value) after one of the calling plugin's settings changes, from code or from the Mods menu.

Detailed description

settings.<key> reads the calling plugin's value; settings.set(key, value) validates and saves it.

Function documentation

add

add(key: str, default: bool | int | float | str | list[str], *, type: str | None = None, label: str | None = None, subtitle: str | None = None, help: str | None = None, min: float | None = None, max: float | None = None, choices: list[str] | None = None) -> Setting

Declare a setting of the calling plugin and return it as a Setting.

The type follows default (bool, int, float or text) unless type says one of:

• "color": a color as "#rrggbb".
• "choice": one of choices.
• "multi": a list of any of choices (a list default with choices implies it). The value lists the chosen items in the order of choices; a choice cannot contain a comma.
• "key": a key name as Unity spells it ("V", "F12", "PageUp"), set in the form by pressing the key.

min and max bound a number. subtitle is a short line the settings form shows under the label; help is longer text shown in a "?" box beside it. The value saved in an earlier session is kept when it is still valid. Declaring a setting gives the plugin a Settings form in the Mods menu. Declare settings when the plugin loads (module body or on_load).

get

get(key: str, default: object = None) -> object

Value of key for the calling plugin.

set

set(key: str, value: object) -> None

Set key for the calling plugin.

as_dict

as_dict() -> dict[str, object]

All settings of the calling plugin.

on_change

on_change(fn: Callable[[str, object], None]) -> Callable[[str, object], None]

Decorator: call fn(key, value) after one of the calling plugin's settings changes, from code or from the Mods menu.

Settings class

Settings of one plugin (ctx.settings in on_load).

Returns	Method
object	get(key: str, default: object = None)	Value of key, or default when there is no such setting.
None	set(key: str, value: object)	Validate against plugin.yml and save.
dict[str, object]	as_dict()	All settings as a dict.

Method documentation

get

get(key: str, default: object = None) -> object

Value of key, or default when there is no such setting.

set

set(key: str, value: object) -> None

Validate against plugin.yml and save. Raises ValueError when out of range.

as_dict

as_dict() -> dict[str, object]

All settings as a dict.

Setting class

One setting the plugin declared with add.

Inherits SettingBinding.

Type	Property
object	value read-only	The saved value; assigning one validates and saves it.

Returns	Method
Callable[[object], None]	on_change(fn: Callable[[object], None])	Decorator: call fn(value) after this setting changes, from code or the Mods menu.

Detailed description

value reads the saved value and, when assigned, validates and saves a new one. Pass the setting itself where the UI takes a value, such as a widget's bind=, and the UI follows every change.

Property documentation

value

value: object [read-only]

The saved value; assigning one validates and saves it.

Method documentation

on_change

on_change(fn: Callable[[object], None]) -> Callable[[object], None]

Decorator: call fn(value) after this setting changes, from code or the Mods menu.

---

Previous: Plugin lifecycle | Next: Raw game access