Entity Plugins

Below is a list of all fields that an entity 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 entity struct
• General
• Attribute Fields
• Rendering
• Nodes
• Selections

---

The entity Struct

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

• _name:string
  The name of the entity.
• _id:integer
  The entity ID.
• _type:string
  The type of the object. This is always "entity".
• nodes:table
  A table of nodes belonging to the entity. 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 entity. Common fields are x, y, width, and height.

General

• name:string
  The internal name of the entity 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 entity.
  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 entity attributes. Each key specifies an attribute name and its value determines the default value that that attribute will have upon placement.

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

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

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

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

• nodeLineRenderType:string or false
nodeLineRenderType(entity):string or false
  May be "line", "fan", "circle", or false. Determines how nodes are visually connected to the main entity. 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 entity.
  • "circle" Used with a single-noded entity. Node spans a circle around the main entity.
  • false Nodes are not visually connected to the main entity.

• nodeLineRenderOffset:{integer, integer}
nodeLineRenderOffset(entity, node, nodeIndex):integer, integer
  The position at which the line connects with the node. Only used when nodeLineRenderType is not false. Defaults to the centre of the node.

• canResize:{boolean, boolean}
canResize(room, entity):boolean, boolean
  A pair of booleans determining whether the entity can be resized along its horizontal and vertical axis, respectively. Defaults to true on the first value if the entity's placement has width and on the second value if the entity's placement has height, false otherwise.

• minimumSize:{integer, integer}
minimumSize(room, entity):integer, integer
  A pair of integers determining the minimum width and height in pixels that an entity may have. Defaults to {8, 8}.

• maximumSize:{integer, integer}
maximumSize(room, entity):integer, integer
  A pair of integers determining the maximum width and height in pixels that an entity may have. Defaults to infinity ({math.huge, math.huge}).

Attribute Fields

• ignoredFields:table
ignoredFields(entity):table
  A list of entity attributes that should not be displayed in the properties menu.
• ignoredFieldsMultiple:table
ignoredFieldsMultiple(entity):table
  A list of additional entity attributes that should not be displayed in the properties menu when multiple entities are selected.
• fieldOrder:table
fieldOrder(entity):table
  A list of entity 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(entity):table
  Key-value pairs of entity 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", or "string". Only "integer" and "color" are usually useful as the other types will typically be guessed from the attribute's current value.
  • 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 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.

Rendering

• sprite(room, entity, viewport):sprite or table
  Used for custom sprite rendering. Returns either a drawable sprite or a list of sprites. Defaults to getting the sprite from texture if defined. Most of the time you'll want to define this one if you need anything more than a single texture.
• texture:string
texture(room, entity):string
  The path to the entity texture relative to Atlases/Gameplay. If not defined, will try to call draw if that is defined, otherwise will try to draw a rectangle.
• draw(room, entity, viewport)
  Highly custom entity drawing. Usually bad for performance; not recommended.
• rectangle(room, entity, viewport):rectangle
  Returns the rectangle used to display the entity. Only used if sprite, texture, and draw are not defined. Defaults to creating a rectangle using the entity's width and height. If the entity has no width and height, a fallback sprite will be used.
• justification:{number, number}
justification(room, entity):{number, number}
  Justification of the sprite along the X and Y axis. Must be a pair of numbers between 0 and 1. Determines the position of the sprite relative to the entity coordinates.
• offset:{integer, integer}
offset(room, entity):{integer, integer}
  X and Y offset of the sprite in pixels. Used to correctly align the sprite to look identical to in-game.
• scale:{integer, integer}
scale(room, entity):{integer, integer}
  X and Y scale of the sprite. Defaults to {1.0, 1.0}.
• rotation:number
rotation(room, entity):number
  Rotation of the sprite (in radians).
• depth:integer
depth(room, entity, viewport):integer
  Determines the render depth of the entity. Larger numbers are further back and smaller numbers are further forward. Negative numbers render in front of the player and positive numbers render behind the player entity. The player entity has a depth of 0.
• color:{r, g, b} or {r, g, b, a}
color(room, entity):{r, g, b} or {r, g, b, a}
  Normalized color table. Determines the tint of the sprite or color of the rectangle. Defaults to {1, 1, 1, 1}.
• mode:string
  Rectangle drawing mode. Only used when drawing a rectangle and only when not using both fillColor and borderColor. May be "fill" or "line".
• fillColor:{r, g, b} or {r, g, b, a}
fillColor(room, entity):{r, g, b} or {r, g, b, a}
  Normalized color table. Only used when drawing a rectangle. Determines the fill color of the rectangle. Defaults to color.
• borderColor:{r, g, b} or {r, g, b, a}
borderColor(room, entity):{r, g, b} or {r, g, b, a}
  Normalized color table. Only used when drawing a rectangle. Determines the border color of the rectangle. Defaults to color.

Nodes

For customizing node rendering, the same functions as in the Rendering section are available, just with the term node in front. Behaviour is identical, with additional parameters.

• nodeSprite(room, entity, node, nodeIndex, viewport):sprite or table
• nodeTexture:string
nodeTexture(room, entity, node, nodeIndex, viewport):string
• nodeDraw(room, entity, node, nodeIndex, viewport)
• nodeRectangle(room, entity, node, nodeIndex, viewport):rectangle
• nodeJustification:{number, number}
nodeJustification(room, entity):{number, number}
• nodeOffset:{integer, integer}
nodeOffset(room, entity):{integer, integer}
• nodeScale:{integer, integer}
nodeScale(room, entity):{integer, integer}
• nodeRotation:number
nodeRotation(room, entity):number
• nodeDepth:integer
nodeDepth(room, entity, viewport):integer
• nodeColor:{r, g, b} or {r, g, b, a}
nodeColor(room, entity, node, nodeIndex):{r, g, b} or {r, g, b, a}
• nodeMode:string
• nodeFillColor:{r, g, b} or {r, g, b, a}
nodeFillColor(room, entity, node, nodeIndex):{r, g, b} or {r, g, b, a}
• nodeBorderColor:{r, g, b} or {r, g, b, a}
nodeBorderColor(room, entity, node, nodeIndex):{r, g, b} or {r, g, b, a}

Selections

• selection(room, entity):rectangle, table of rectangles
  Used for fine control over selections. Returns the main selection rectangle and a table of all node selection rectangles. If no nodes are present, the second return value may be nil or an empty table. Often implemented using utils.rectangle. Defaults to rectangle() if defined, otherwise creates a rectangle based on entity width and height. If the entity has no width and height, the default rectangle will try to fully cover the drawable texture.
• onNodeAdded(room, entity, nodeIndex)
  Callback that is run whenever a new node is added to the entity. nodeIndex is the index of the currently selected node. Return false to cancel the action.
• nodeAdded(room, entity, nodeIndex):boolean
  Overwrites node-adding behaviour. Allows manually modifying entity.nodes. nodeIndex is the index of the currently selected node. Returns true if a node has been successfully added, false otherwise.
• onDelete(room, entity, nodeIndex)
  Callback that is run whenever an entity or node is deleted. A node index of 0 means the entity itself. Return false to cancel the action.
• delete(room, entity, nodeIndex):boolean
  Overwrites deletion behaviour. A node index of 0 means the entity itself. Returns true if the object has been successfully deleted, false otherwise.
• onResize(room, entity, offsetX, offsetY, directionX, directionY)
  Callback that is run whenever an entity is being resized. Return false to cancel the action.
• resize(room, entity, offsetX, offsetY, directionX, directionY):boolean
  Overwrites resizing behaviour. Returns true if any changes have been made, false otherwise.
• updateResizeSelection(room, entity, nodeIndex, selection, offsetX, offsetY, directionX, directionY)
  Overwrites resize selection update. Allows manually changing the selection rectangle after a resize. A node index of 0 means the entity itself.
• onMove(room, entity, nodeIndex, offsetX, offsetY)
  Callback that is run whenever an entity or node is being moved. A node index of 0 means the entity itself. Return false to cancel the action.
• move(room, entity, nodeIndex, offsetX, offsetY)
  Overwrites moving behaviour. Allows manually modifying entity or node coordinates on move. A node index of 0 means the entity itself.
• updateMoveSelection(room, entity, nodeIndex, selection, offsetX, offsetY)
  Overwrites move selection update. Allows manually changing the selection rectangle after a move. A node index of 0 means the entity itself.