Trigger Plugins

Below is a list of all fields that a trigger 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 trigger struct
• General
• Attribute Fields

---

The trigger Struct

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

• _name:string
  The name of the trigger.
• _id:integer
  The entity ID.
• _type:string
  The type of the object. This is always "trigger".
• nodes:table
  A table of nodes belonging to the trigger. Each node is a coordinate table in pixels in the form of {x = 8, y = 8}.

In addition to these, the struct contains all data attributes defined in the placement used for the trigger. Triggers always have x, y, width, and height.

General

• name:string
  The internal name of the trigger as defined in the mod

• placements:table
  A table containing placement information. May either contain the information directly, or multiple tables of placement information, in case there is a need for multiple placements for a single trigger.
  Placement information consists of up to three fields:

  • name:string
    The name of the placement. Used to look up human-readable text in the language file.
  • placementType:string
    May be point, line, or rectangle. Determines behaviour during placement. Will usually be guessed from other data.
  • data:table
    Key-value pairs of trigger attributes. Each key specifies an attribute name and its value determines the default value that that attribute will have upon placement.

• associatedMods:table
associatedMods(trigger):table
  A list of mod names as specified in the mods' everest.yaml that are associated with this trigger. Used for displaying the mod name behind the trigger name in the placement list, and when determining dependencies of a map that contains this trigger. Defaults to a one-element list with the name of the mod containing this plugin.

• nodeLimits:{min, max}
nodeLimits(room, trigger):min, max
  A pair of integers specifying the minimum and maximum number of nodes that this trigger can have. Defaults to {0,0}. If the maximum value is -1, there is no upper limit.

• nodeVisibility:string
nodeVisibility(trigger):string
  May be one of the strings "never", "selected", or "always". Determines when the trigger's nodes are to be rendered. Defaults to "selected".

  • "never" Nodes are never visible.
  • "selected" Nodes are visible when the trigger is selected.
  • "always" Nodes are always visible.

• nodeLineRenderType:string or false
nodeLineRenderType(trigger):string or false
  May be "line", "fan", "circle", or false. Determines how nodes are visually connected to the main trigger. Defaults to false.

  • "line" Each node is visually connected to the previous and next node in the list, forming a line.
  • "fan" Each node is visually connected directly to the main trigger.
  • "circle" Used with a single-noded trigger. Node spans a circle around the main trigger.
  • false Nodes are not visually connected to the main trigger.

• triggerText:string
triggerText(room, trigger):string
  Custom text to be displayed by the trigger. Replaces the default trigger name display.

• category:string
category(trigger):string
  General category this trigger belongs to. Determines the colour of the trigger and the View category it is displayed with. May be one of camera, audio, visual, or default. Defaults to default.

Attribute Fields

• ignoredFields:table
ignoredFields(trigger):table
  A list of trigger attributes that should not be displayed in the properties menu. Defaults to {"_name", "_id", "originX", "originY"}.
• ignoredFieldsMultiple:table
ignoredFieldsMultiple(trigger):table
  A list of additional trigger attributes that should not be displayed in the properties menu when multiple triggers are selected.
• ignoredSimilarityKeys:table
ignoredSimilarityKeys(trigger):table
  A list of trigger fields and attributes that should not be considered when checking for similar triggers to select in strict mode. Defaults to {"_name", "_id", "_type", "originX", "originY", "x", "y"}.
• fieldOrder:table
fieldOrder(trigger):table
  A list of trigger attributes specifying the order that these attributes will be displayed in in the properties menu. Any attribute not specified in this table will be added to the end of the menu in alphabetical order. Defaults to displaying x, y, width and height at the top.
• fieldInformation:table
fieldInformation(trigger):table
  Key-value pairs of trigger attributes. Each key is an attribute name as specified in the placement data 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 trigger attributes have their default value specified in the placement. Should a new attribute be added to the trigger at a later time, triggers 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 properties 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.