Documentation

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.


Page updated 30 days ago by Miss(Trusted developer)