Plugin settings

Plugins can save settings in the Openplanet settings file, which can then be edited from within Openplanet's settings window. To define a setting, all you have to do is create a global variable and add a Setting metadata line to it.

[Setting name="Something"]
bool Setting_Something;

Supported types

The following types are supported:

bool
int (including int8, int16, int32)
uint (including uint8, uint16, uint32)
float
double
string
vec2, vec3, vec4
int2, int3
nat2, nat3
quat
Any enum

Default values

Settings can have default values. When they are not user-defined, the setting will be the default value, which is specified by the initial global variable value. The user can also choose to reset every setting back to its default value within Openplanet's settings dialog.

[Setting name="Amount"]
int Setting_Amount = 10;

Note that settings that are set to their default value will not be saved in the settings. That means that if you change your default value, people who were previously on that default value will now also have your changed value.

Attributes

The Setting metadata supports a number of attributes depending on which type your setting variable is. All attributes are optional, however. The following attributes are supported for every type:

Name	Description
`name`	The name displayed in the settings dialog.
`description`	The description displayed in the settings dialog, as a little question mark icon next to the setting with a tooltip.
`category`	The category for the setting. This will automatically create multiple tabs, where each category is its own tab.
`hidden`	Takes no value. Marks the setting so it will not be displayed in the Openplanet settings dialog.
`if`	Conditional expression (evaluated at runtime) whether to display this setting in the settings window. Should be the name of a function, or a global variable that is either a boolean or an enum value. For booleans you can use expressions like `if="Setting_Display"`, `if="!Setting_Display"`, and for enums you can use expressions like `if="Setting_DisplayType SomeValueName"`, `if="!Setting_DisplayType SomeValueName"`. Note that they don't necessarily have to be settings themselves. For functions, this may be an expression like `if="IsValid"`, `if="!IsValid"`. (Requires 1.26.26 or newer)
`beforerender`	Function to call before this setting is rendered in the settings window. Must point to a global function with signature `void SomeCallback()`. (Requires 1.27.0 or newer)
`afterrender`	Function to call after this setting is rendered in the settings window. Must point to a global function with signature `void SomeCallback()`. (Requires 1.27.0 or newer)

A few types allow a couple more attributes:

Types	Name	Description
`int`, `uint`, `float`, `double`	`min`	The minimum possible value. When combined with `max`, turns it into a slider.
`int`, `uint`, `float`, `double`	`max`	The maximum possible value. When combined with `min`, turns it into a slider.
`int`, `uint`, `float`, `double`, `vec2`, `vec3`, `vec4`	`drag`	Whether to make this a draggable setting rather than where the user must type the value.
`vec3`, `vec4`	`color`	Whether this is a color setting. Includes a color picker.
`string`	`max`	The maximum possible length of the string.
`string`	`multiline`	Takes no value. Marks this string as being a multiline input field.
`string`	`password`	Takes no value. Marks this string as being a password, masking the characters with asterisks in the settings dialog.
`int`, `uint`, `float`, `double`	`step`	The step size for drag and input fields. (Requires 1.26.26 or newer)

Hidden settings

Settings can be made hidden by using the hidden attribute. This will make them not appear on the Openplanet settings dialog, which is useful if you want to programatically store some settings manually. Don't put too much content into these, however!

[Setting hidden]
bool Setting_MyHiddenSetting;

Settings tabs

You can create your own scripted settings tabs in the Openplanet settings dialog. To do this, mark a global function with [SettingsTab], like this:

[SettingsTab]
void RenderSettings()
{
  if (UI::Button("Click me!")) {
    print("You clicked the button");
  }
}

By default, the tab will be named Script. You can change this by passing the name attribute, for example [SettingsTab name="Widgets"]. You can also use a different icon for this using the icon attribute, for example [SettingsTab name="Tags" icon="Tag"].

You may also pass order="n" where n is a number to specify a specific order of tabs.