Effect Plugins

Below is a list of all fields that an effect plugin may contain. Some fields may contain either values directly, or a function returning an equivalent value.

Almost all functions are optional and should only be used to overwrite default behaviour if necessary.

---

Table of contents

• The effect and style structs
• General
• Attribute Fields

---

The effect and style Structs

Some functions specified below make use of the effect object. It contains a few important fields:

• _name:string
  The name of the effect.
• _type:string
  The type of the object. This is always "effect" for custom effects.

Most functions make use of the style object. It is a list of effect, apply, and parallax objects specifying the current list of effects, applies, and parallaxes in the map. An apply is a struct with the _type field set to "apply", and a parallax is a struct with the _type set to "parallax". All custom effects will be of type effect.

General

• name:string
  The internal name of the effect as defined in the mod
• canForeground:boolean
canForeground(style):boolean
  Allows the effect to be in the foreground if true. Defaults to true.
• canBackground:boolean
canBackground(style):boolean
  Allows the effect to be in the background if true. Defaults to true.
• associatedMods:table
associatedMods(effect):table
  A list of mod names as specified in the mods' everest.yaml that are associated with this effect. Used for displaying the mod name behind the effect name in the effect list, and when determining dependencies of a map that contains this effect. Defaults to a one-element list with the name of the mod containing this plugin.

Attribute Fields

• defaultData:table
defaultData(style):table
  Key-value pairs of effect attributes. Each key specifies an attribute name and its value determines the default value that that attribute will have upon adding the effect.
• ignoredFields:table
ignoredFields(style):table
  A list of effect attributes that should not be displayed in the styleground menu.
• fieldOrder:table
fieldOrder(style):table
  A list of effect attributes specifying the order that these attributes will be displayed in in the styleground menu. Any attribute not specified in this table will be added to the end of the menu in alphabetical order. Adding "only","exclude","tag","flag","notflag" at the start will preserve the order of default attributes.
• fieldInformation:table
fieldInformation(style):table
  Key-value pairs of effect attributes. Each key is an attribute name as specified in defaultData and its value is a table specifying additional metadata relevant for displaying the attribute's value. Custom form fields may add their own options here.
  • fieldType:string
    Determines the type of field used to display and validate the attribute. May be "integer", "color", "boolean", "number", "string", or "list". Only "integer", "color", and "list" are usually useful as the other types will typically be guessed from the attribute's current value.
  • default
    An optional default value. Normally, all attributes have their default value specified in the placement. Should a new attribute be added to the effect at a later time, effects that are already placed would not have the attribute. Setting this option fills the potentially empty field with the specified value if needed.
  • minimumValue:integer or number
    Used with the "integer" and "number" field types. Determines the minimum allowed value for that attribute. Defaults to negative infinity (-math.huge)
  • maximumValue:integer or number
    Used with the "integer" and "number" field types. Determines the maximum allowed value for that attribute. Defaults to positive infinity (math.huge)
  • validator(string):boolean
    Used with the "string" field type. Returns true if the input string is valid for the attribute. Defaults to accepting any string.
  • valueTransformer(string):string
    Used with the "string" field type. Converts the string from what is displayed in the attribute field into the stored attribute data. Defaults to the identity.
  • displayTransformer(string):string
    Used with the "string" field type. Converts the string from the the stored attribute data into a string used for display in the attribute field. Defaults to the identity.
  • options:table
    Used with any textfield-type field and turns it into a dropdown. Contains key-value pairs where each key is the option as displayed in the styleground window and its value is the value written to the attribute. Options are sorted alphabetically. If custom order is needed, may also be a list of pairs in the form {text, value}.
  • editable:boolean
    Used with any textfield-type field if options is defined. Turns the dropdown into an editable dropdown if true, allowing manual entry of values that are not part of options. Defaults to false.
  • allowXNAColors:boolean
    Used with the "color" field type. Determines whether the "color" field can accept XNA Color names rather than only numerical colors. Defaults to false.
  • allowEmpty:boolean
    Used with the "color" field type. Determines whether the field may be left empty. Defaults to false.
  • useAlpha:boolean
    Used with the "color" field type. Determines whether the colour should contain a configurable alpha value. Defaults to false.
  • elementOptions:table
    Used with the "list" field type. Determines the type and options of the individual elements in the list. Has the same structure as fieldInformation itself for the element field.
  • elementDefault
    Used with the "list" field type. Determines the default value a new list element should have after being added to the list.
  • elementSeparator:string
    Used with the "list" field type. Determines the separator used between list elements. Defaults to comma.
  • minimumElements:integer
    Used with the "list" field type. Determines the minimum number of elements allowed for the list to be valid. Defaults to 0.
  • maximumElements:integer
    Used with the "list" field type. Determines the maximum number of elements allowed for the list to be valid. Defaults to positive infinity.