Layer

Layers are arranged as a stack within a sprite. Layers may nest within each other to form a hierarchy. Layers that accept children are group layers.

A layer can be created with Sprite:newLayer. A group layer can be created with Sprite:newGroup. Layers can be removed with Sprite:deleteLayer.

Layer.sprite

Gets the sprite to which this layer belongs.

Layer.name

Gets or sets the layer name, a string.

Layer.opacity

local opacity = layer.opacity
layer.opacity = newOpacity

Gets or sets the layer opacity, a value from 0 to 255. The layer is completely transparent when the value is 0; opaque when the value is 255. When the layer is a background, returns 255.

When the layer is a group, returns nil.

Layer.blendMode

local blendMode = layer.blendMode
layer.blendMode = newBlendMode

Gets or sets the layer blending mode (how colors are blend with the layer below). It's expressed as an integer or a value from the BlendMode enumeration.

When the layer is a group, this property is nil.

Layer.layers

If a layer is a group, gets the table of child layers for which the group serves as a parent. If the layer is not a group, returns nil.

Layer.parent

local spriteOrLayerGroup = layer.parent
layer.parent = sprite
layer.parent = group

Gets or sets the layer's parent. The parent may be either a sprite or a group layer.

Upon setting the parent, the child layer is moved to the top of the parent's layer stack. Throws an error if the parent layer is not a group or if the setter tries to parent a layer to itself.

Layer.stackIndex

local index = layer.stackIndex
layer.stackIndex = newPosition

Gets or sets the layer's index in its parent's layers table. In other words, this is the layer's place in the local stack. Layers stack in descending order. For example, a layer with index 1 will lie beneath a layer with index 2, assuming the layers share the same parent.

Layer.isImage

Gets whether or not the layer contains cels with images.

Layer.isGroup

Gets whether or not the layer is a group and has the capacity to be a parent to other layers. A layer may be a group, yet have no children; in such a case, its layers property will return a table of zero length.

Groups may nest within groups, creating a hierarchy.

Layer.isTilemap

Returns true if the layer is a tilemap (contains a tileset)

Layer.isTransparent

Gets whether or not a layer supports transparency. The opposite of the property Layer.isBackground. For indexed color mode, the layer may contain images with a transparent color index. For RGB or grayscale color mode, the layer may contain images with an alpha channel.

Returns true if the layer is a group.

For context, see the general documentation on layers.

Layer.isBackground

Gets whether or not a layer is a background. The opposite of the property Layer.isTransparent. Background layers do not contain images which support transparency. Returns false if the layer is a group.

For context, see the general documentation on layers.

Layer.isEditable

Gets or sets whether a layer is editable, unlocked in other words.

It describes only the group layer's local editability, not whether any hierarchy that contains it is editable. See Layer.isVisible for an example snippet using a similar property.

Layer.isVisible

local visible = layer.isVisible
layer.isVisible = visible

Gets or sets whether or not the layer is visible.

It describes only the layer's local visibility, not its visibility with respect to the hierarchy that contains it. For example, in the following code layer1.isVisible will be true (even when the parnet group visibility is false):

local sprite = app.sprite
local layerGroup = sprite:newGroup()
local layers = sprite.layers
local layer1 = layers[1]
layer1.parent = layerGroup
layerGroup.isVisible = false
layer1.isVisible = true
print(layer1.isVisible)

Layer.isContinuous

Gets or sets whether a layer biases toward linked cels when a new cel is created in the timeline.

Returns false if the layer is a group.

For context, see the general documentation on continuous layers.

Layer.isCollapsed

Gets or sets whether or not a group layer is collapsed, i.e., whether its child layers are hidden in the timeline. The opposite of the property Layer.isExpanded.

It describes only the group layer's local collapse, not whether any hierarchy that contains it is collapsed. See Layer.isVisible for an example snippet using a similar property.

Layer.isExpanded

Gets or sets whether or not a group layer is expanded, meaning whether its child layers are visible in the timeline. The opposite of the property Layer.isCollapsed.

It describes only the group layer's local expansion, not whether any hierarchy that contains it is expanded. See Layer.isVisible for an example snippet using a similar property.

Layer.isReference

local isRef = layer.isReference

Gets whether or not the layer is a reference layer. You cannot change the value of this property.

Layer.cels

Gets a table of cels in the layer. If the layer is a group, this property will return a table of zero length.

See also the Layer:cel() function.

Layer.color

local color = layer.color
layer.color = color

Gets or sets the user-defined color of this layer in the timeline.

Layer.data

local data = layer.data
layer.data = data

Gets or sets the user-defined data related to this layer (a text string).

Layer.properties

Access user-defined and extension-defined properties of this layer.

Layer:cel()

local cel = layer:cel(frameNumber)
assert(cel == layer:cel(sprite.frames[frameNumber]))

Returns a cel, if any, at the intersection of the layer and a frame. The frame may be either a frame object or its frame number, an integer. If there is no cel at that intersection, returns nil.

Layer.tileset

local tileset = layer.tileset
layer.tileset = newTileset

Gets or sets the tileset associated to this layer only when it's a tilemap (returns nil in other case).