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.
| Parameter | Type | Description |
|---|---|---|
key Required | String | The key to be retrieved. |
| defaultValue | * | The value to be returned if the key does not exist. |
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.
| Parameter | Type | Description |
|---|---|---|
key Required | String | The key to merge. |
value Required | * | The value to merge. |
Undefined.
Type:Undefined Target:Unit
Sets the setting to the settings asset.
| Parameter | Type | Description |
|---|---|---|
key Required | String | The key to set. |
value Required | * | The value to set. |
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.
| Parameter | Type | Description |
|---|---|---|
options Required | Object | Options passed to the event to be triggered. Has the following keys: |
“settings” Required | Object | The unit settings. |
Undefined.
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.