SettingPerk

Inherits:Perk Section:setting Priority:10

SettingPerk grants functions related to the unit's settings.

Settings common to all units are written in the “system.setting” section of the global settings.

{
    "system": {
        "setting": {
            "options": {
                "path": String,
                "settingFormat": "js"|"json",
                "settingsRef": Boolean|String,
            }
        }
    }
}

Unit-specific settings are written in the “setting” section.

{
    "setting": {
        "options": {
            "autoLoad": String,
            "fileName": String,
            "path": String,
            "settingFormat": "js"|"json",
            "settingsRef": Boolean|String,
        }
    }
}

Some settings can be written in tag attributes.

<my-unit
    bm-autoload=String
    bm-filename=String
    bm-options=String
    bm-path=String
    bm-settingref=Empty|String|"false"
></my-unit>

Type:String Default:False

Indicates that the unit will automatically load the necessary files. This is essentially a UnitPerk setting, but if a URL is specified here, SettingPerk will use it as the path and file name of the settings file.

Type:String

Settings string in JSON format. The settings specified here will be merged into the “options” section of the unit settings.

Type:String Default:<tag name>

The Setting file name. No extension is required.

The priority, in higher order, is “setting.options.fileName”, "unit.options.fileName". If all of them are not available, then the tag name is used as the file name.

Loads a file with the filename + extension “settings.js”.

Type:String

The path to the setting file. The final path is the path concatenated with the path in the global settings and the path in the unit-specific settings.

The global settings are used in the following order of precedence: “system.setting.options.path”, “system.unit.options.path” and unit-specific settings are used in the following order of precedence: “setting.options.path”, “unit.options.path”.

Type:String Default:“json”

The format of the setting file. “js” or “json” can be specified. If not specified, the file is treated as a JSON file.

Type:Boolean|String Default:False

The URL to the unit's settings file or Boolean. If True, the default URL is used. The settings are read asynchronously and merged into the unit's settings.

If the value is set in the bm-settingsref attribute, it is assumed to be the URL to the file. It is treated as true if no value is specified. To specify false, specify the string “false”.

Type:ChainableStore Target:Instance

This asset holds the unit's settings.

Type:* Target:Unit

Retrieves settings from the settings asset.

The value of the specified key. If the key is not found, the defalutValue parameter is returned if specified, or Undefined if not specified.

Type:Undefined Target:Unit

Merges settings.

Undefined.

Type:Undefined Target:Unit

Sets the setting to the settings asset.

Undefined.

Type:Undefined Target:Unit

Triggers events to apply the settings. It also uses the "perk.attachPerks" spell between “beforeApplySettings” and “doApplySettings” to attach the necessary perks.

Undefined.

• beforeApplySettings
• doApplySettings
• afterApplySettings

Type:Undefined Target:Unit

Loads the unit's external settings file. The loaded settings are merged into the unit's settings. The file to load is specified by settingsRef/bm-settingsref.

If the settings format is a Javascript object, “this” can be used to refer to the unit in the settings since the unit is bound to the object.

None.

Undefined.

• setting.options.settingRef/bm-settingsref
• setting.options.settingFormat/system.setting.options.settingFormat
• system.unit.options.path
• unit.options.path
• unit.options.fileName
• unit.options.query