Skip to content

Plugin Configuration

tobspr edited this page Nov 24, 2015 · 14 revisions

Writing plugin configurations

Each plugin has to have its own configuration file, named config.yaml. In that configuration file, information about the plugin and settings are contained.

Each configuration file needs to contain at least these fields:

name: PluginName
author: your_name <[email protected]>
version: 1.0
description: This plugin adds support for some Feature.
settings:
    -- see below
daytime_settings:
    -- see below

The above fields should be self-explanatory. The settings field has to be always present, even if the plugin has no settings.

Settings

settings should be a yaml-dictionary where the key denotes the identifier of the setting, and the contents specify the contents of the setting. For example:

settings:
    my_setting:
        -- setting options, see below
    other_setting:
        -- setting options, see below

To query settings, see the [Plugin API](Plugin API).


Each setting consists of atleast a type, default, label and description. There are 4 different setting types: int, float, enum and bool where you can choose from. Each settings type adds a few additional options which can be specified. Below you can find a list of examples for those types:

Int-Settings
some_int_setting:
    type: int
    range: [0, 10]
    default: 5
    label: Some integer setting
    description: Description of the setting.
Float-Settings
some_float_setting:
    type: float
    range: [-5.3, 2.9]
    default: 2.5
    label: Some float setting
    description: Description of the setting.
Boolean-Settings
some_bool:
    type: bool
    default: false
    label: Some boolean setting
    description: Description of the setting.
Enum-Settings
some_enum:
    type: enum
    values: [value1, value2, value3]
    default: value2
    label: Some enum setting
    description: Description of the setting.

Runtime Settings

Each setting can be specified as dynamic by adding either runtime: true or shader_runtime: true.

If you specify a setting as runtime, it denotes that the setting can be changed at runtime, without major changes. (E.g. a setting which just changes a shader input should be noted as runtime). You should add a hook for when the setting got changed (see [Plugin API](Plugin API)), and do the required work to update the setting when the hook get called.

If you specify a setting as shader_runtime, it denotes that the setting can be changed at runtime, but the plugin shaders have to get recompiled when changing the setting. This is typical for settings like sample count, boolean flags which enable / disable features and so on. If a setting noted as shader_runtime gets changed, the pipeline will call the hook bound to that setting (if it exists), and reload all shaders of the plugin after that. Most of the time you don't need to write your custom hooks for shader runtime settings.

Additional Setting Parameters

There are various additional parameters you can add to your configuration variables:

my_setting:
    -- Only displays the setting in the plugin configurator if my_other_setting is true and
    -- another_setting has the value "someval". Notice you can only reference boolean and
    -- enum properties.
    display_if: {my_other_setting: true, another_setting: "someval"}

Daytime Settings

TODO: Write me